simple, expressive API for tailwindcss + react-native
npm install twrnc> A simple, expressive API for TailwindCSS + React Native, written in TypeScript
``jsx
import { View, Text } from 'react-native';
import tw from 'twrnc';
const MyComponent = () => (
}>
}>Hello World
);
`
- full support for all _native_ RN styles with tailwind counterparts:
(view,
layout,
image,
shadow, and
text).
- very fast: best performance of all RN styling libraries, according to
this benchmark.
- compatible with Tailwind CSS v3 and v2
- respects your tailwind.config.js for full configurationandroid:mt-4 ios:mt-2
- platform prefixes:
- dark mode support:
- media query support: (also, arbitrary: min-w-[600px]:flex-wrap)portrait:flex-col landscape:flex-row
- device orientation prefixes:
- and vh unit support: h-screen, min-w-screen, w-[25vw], etc...retina
- device pixel density prefix: w-4 retina:w-2
- arbitrary, JIT-style classes: , etc...
- tagged template literal syntax for most common usage
- merges supplied RN style objects for unsupported utilities or complex use cases
- supports custom utility creation via standard
plugin config.
- flexible, conditional styles based on
classnames package api.
- written 100% in TypeScript, ships with types
- Installation
- API
- Customization
- Enabling Device-Context Prefixes
- Taking Control of Dark Mode
- Customizing Breakpoints
- Adding Custom Classes
- Matching Conditional Prefixes
- Box-Shadows
- RN-Only Additions
- JIT-style Arbitrary Values
- VS Code Intellisense
- JetBrains IDEs Intellisense
- Memo-Busting
- Migrating from previous versions
- Prior Art
`bash`
npm install twrnc
The default export is an ES6 _Tagged template function_ which is nice and terse for the
most common use case -- passing a bunch of space-separated Tailwind classes and getting
back a react-native style object:
`js
import tw from 'twrnc';
twpt-6 bg-blue-100;`
// -> { paddingTop: 24, backgroundColor: 'rgba(219, 234, 254, 1)' }
In the spirit of Tailwindcss's intuitive responsive prefix syntax, twrnc adds support
for platform prefixes to conditionally apply styles based on the current platform:
`jsios:pt-4 android:pt-2
// 😎 styles only added if platform matches
tw;`
Media query-like breakpoint prefixes supported (see
Breakpoints for configuration):
`jsflex-col lg:flex-row
// 😎 faux media queries
tw;`
Dark mode support (see here for configuration);
`jsbg-white dark:bg-black
// 😎 dark mode support
tw;`
You can also use tw.style() for handling more complex class name declarations. The api
for this function is directly taken from the excellent
classnames package.
`js
// pass multiple args
tw.style('text-sm', 'bg-blue-100', 'flex-row mb-2');
// arrays of classnames work too
tw.style(['text-sm', 'bg-blue-100']);
// falsy stuff is ignored, so you can do conditionals like this
tw.style(isOpen && 'bg-blue-100');
// { [className]: boolean } style - key class only added if value is true
tw.style({
'bg-blue-100': isActive,
'text-red-500': invalid,
});
// or, combine tailwind classes with plain react-native style object:
tw.style('bg-blue-100', { resizeMode: repeat });
// mix and match input styles as much as you want
tw.style('bg-blue-100', ['flex-row'], { 'text-xs': true }, { fontSize: 9 });
`
If you need some styling that is not supported in a utility class, or just want to do some
custom run-time logic, you can pass raw RN style objects to tw.style(), and they get
merged in with the styles generated from any other utility classes:
`jsmt-1
tw.style(, {repeat
resizeMode: ,${progress}%
width: ,`
});
// -> { marginTop: 4, resizeMode: 'repeat', width: '32%' }
The tw function also has a method color that can be used to get back a string value of
a tailwind color. Especially useful if you're using a customized color palette.
`jsbg|text|border-blue-100
tw.color('blue-100'); // also work`
// -> "rgba(219, 234, 254, 1)"
You can import the main tw function and reach for tw.style only when you need it:
`jsx
import tw from 'twrnc';
const MyComponent = () => (
}>
);
`
...or if the tagged template function isn't your cup of tea, just import tw.style astw:
`jsx
import { style as tw } from 'twrnc';
const MyComponent = () => (
);
`
You can use twrnc right out of the box if you haven't customized yourtailwind.config.js file at all. But more likely you've got some important app-specifictw
tailwind customizations you'd like to use. For that reason, we expose the ability to
create a custom configured version of the function object.
`js
// lib/tailwind.js
import { create } from 'twrnc';
// create the customized version...
const tw = create(require(../../tailwind.config.js)); // <- your path may differ
// ... and then this becomes the main function your app uses
export default tw;
`
...and in your component files import your own customized version of the function instead:
`jsx`
// SomeComponent.js
import tw from './lib/tailwind';
> [!note]
> If you are using export default {} in your tailwind.config.js file, you needdefault
> to pass the to create util from your config require:require('../../tailwind.config.js').default
> .
To enable prefixes that require runtime device data, like _dark mode_, and _screen size
breakpoints_, etc., you need to connect the tw function with a dynamic source of deviceuseDeviceContext
context information. The library exports a React hook called that takes
care of this for you. It should be included one time, at the _root of your component
hierarchy,_ as shown below:
`jsxfrom 'twrnc'
import tw from './lib/tailwind'; // or, if no custom config:
import { useDeviceContext } from 'twrnc';
export default function App() {
useDeviceContext(tw); // <- 👋
return (
}>
}>Hello
);
}
`
> ⚠️ If you're using Expo, make sure to make the following change in app.json to use thedark:
> prefix as Expo by default locks your app to light mode only.
`json`
{
"expo": {
"userInterfaceStyle": "automatic"
}
}
By default, if you use useDeviceContext() as outlined above, your app will respond to
ambient changes in the _device's color scheme_ (set in system preferences). If you'd
prefer to explicitly control the color scheme of your app with some in-app mechanism,
you'll need to configure things slightly differently:
`jsx
import { useDeviceContext, useAppColorScheme } from 'twrnc';
export default function App() {
useDeviceContext(tw, {
// 1️⃣ opt OUT of listening to DEVICE color scheme events
observeDeviceColorSchemeChanges: false,
// 2️⃣ and supply an initial color scheme
initialColorScheme: light, // 'light' | 'dark' | 'device'
});
// 3️⃣ use the useAppColorScheme hook anywhere to get a reference to the current
// colorscheme, with functions to modify it (triggering re-renders) when you need
const [colorScheme, toggleColorScheme, setColorScheme] = useAppColorScheme(tw);
return (
// 4️⃣ use one of the setter functions, like toggleColorScheme in your app`
}>Switch Color Scheme
);
}
You can customize the breakpoints in the same way as a
tailwindcss web project, using
tailwind.config.js. The defaults that ship with tailwindcss are geared towards the
web, so you likely want to set your own for device sizes you're interested in, like this:
`jstablet:flex-row
// tailwind.config.js
module.exports = {
theme: {
screens: {
sm: '380px',
md: '420px',
lg: '680px',
// or maybe name them after devices for
tablet: '1024px',
},
},
};
To add custom utilities, use the
plugin method
described in the tailwind docs, instead of writing to a .css file.
`js
const plugin = require('tailwindcss/plugin');
module.exports = {
plugins: [
plugin(({ addUtilities }) => {
addUtilities({
'.btn': {
padding: 3,
borderRadius: 10,
textTransform: uppercase,#333
backgroundColor: ,repeat
},
'.resize-repeat': {
resizeMode: ,`
},
});
}),
],
};
Wil also allow you to supply a string of other utility classes (similar to @apply),
instead of using CSS-in-JS style objects:
`js@apply
module.exports = {
plugins: [
plugin(({ addUtilities }) => {
addUtilities({
// 😎 similar to
'.btn': ,font-serif leading-relaxed tracking-wide text-gray-800
'.body-text': ,`
});
}),
],
};
twrnc also exposes a tw.prefixMatch(...prefixes: string[]) => boolean function thattw
allows you to test whether a given prefix (or combination of prefixes) would produce a
style given the current device context. This can be useful when you need to pass some
primitive value to a component, and wish you could leverage 's knowledge of thePlatform
current device, or really anywhere you just need to do some logic based on the device
context. This could also be accomplished by importing or a combination of othertw
RN hooks, but chances are you've already imported your function, and this saves you
re-implementing all that logic on your own:
`tsx`
const SomeComponent = () => (
) ? 60 : 90} />ios
{tw.prefixMatch(, dark) ?
);
Box shadows in CSS
differ substantially from shadow in RN, so
this library doesn't attempt to parse CSS box-shadow strings and translate them into RN
style objects. Instead, it offers a number of low-level utilities not present in
tailwindcss, which map to the
4 shadow props in RN:
`jsshadowColor
// RN
tw; // > { shadowColor: #fff }shadow-red-200
tw; // > { shadowColor: #fff }shadow-[#eaeaea]
tw; // > { shadowColor: #eaeaea }shadow-black shadow-opacity-50
tw; // > { shadowColor: rgba(0,0,0,0.5) }
// RN shadowOffset
tw; // > { shadowOffset: { width: 4, height: 4 } }shadow-offset-2/3
tw; // > { shadowOffset: { width: 8, height: 12 } }shadow-offset-[3px]
tw; // > { shadowOffset: { width: 3, height: 3 } }],shadow-offset-[4px]/[5px]
tw; // > { shadowOffset: { width: 4, height: 5 } }],
// RN shadowOpacity
tw; // { shadowOpacity: 0.5 }
// RN shadowRadius
tw; // { shadowRadius: 4 }shadow-radius-[10px]
tw; // { shadowRadius: 10 }`
We also provide a _default implementation_ of the shadow- utils
provided by tailwindcss, so you can use:
`jsshadow-md
tw;#000
/*
-> {
shadowOffset: { width: 1, height: 1 },
shadowColor: ,`
shadowRadius: 3,
shadowOpacity: 0.125,
elevation: 3,
}
*/
To override the default implementations of these named shadow classes,
add your own custom utilities -- any custom utilities you
provide with the same names will override the ones this library ships with.
twrnc implements all of the tailwind utilities which overlap with supported RN (native,
not web) style props. But it also adds a sprinkling of RN-only utilities which don't map
to web-css, including:
- low-level shadow utilities
- elevation (Android
only), eg: elevation-1, elevation-4
- -> {fontVariant: 'small-caps'}
- number based font-weight utilities , font-400, (100...900)direction-(inherit|ltr|rtl)
-
- via self-baseline
- and remove-font-padding (Android only: includeFontPadding)tint-{color}
- image tint color control ( e.g. tint-red-200)pointer-events-(box-only|box-none)
-
Many of the arbitrary-style utilities made possible by Tailwind JIT are implemented in
twrnc, including:
- arbitrary colors: bg-[#f0f], text-[rgb(33,45,55)]
- negative values: , -tracking-[2px]
- shorthand color opacity: (red-200 at 75% opacity)border-black border-opacity-75
- merging color/opacity:
- arbitrary opacity amounts:
- custom spacing: , -pb-[3px], tracking-[2px]
- arbitrary fractional insets: , left-5/8
- arbitrary min/max width/height: , max-h-3/8, w-[25vw], h-[21px]
- arbitrary breakpoints: , max-h-[1200px]:p-4
Not every utility currently supports all variations of arbitrary values, so if you come
across one you feel is missing, open an issue or a PR.
Add the following to the settings of the
official Tailwind plugin
for VS Code.
`jsonc`
// ...
"tailwindCSS.classAttributes": [
// ...
"style"
],
"tailwindCSS.classFunctions": ["tw", "tw.color", "tw.style"],
More detailed instructions, including how to add snippets, are available
here.
For JetBrains IDEs (WebStorm, IntelliJ, etc.) Go to Settings | Languages & Frameworks |
Style Sheets | Tailwind CSS. Add the following configuration options:
`jsonc`
// ...
"classAttributes": [
// ...
"style"
],
"classFunctions": ["tw", "tw.color", "tw.style"],
It is important that you have a tailwind.config.js in the root of the repository even ifexport default {}
the content is just , otherwise the Tailwind LSP won't start correctly.
If you're using device-context prefixes (like dark:, and md:), _memoized_ componentsreact-navigation
can cause problems by preventing re-renders when the color scheme or window size changes.
You may not be memoizing explicitly yourself as many third-party libraries (like) memoizes their own components.
In order to help with this problem, twrnc exposes a .memoBuster property on the tw
object. This string property is meant to passed as a prop to break memoization
boundaries. It is stable (preventing re-renders) until something in the device context
changes, at which point it deterministically updates:
`tsx`
> This is not a perfect solution for all memoization issues. For caveats and more
> context, see
> #112.
See migration-guide.md.
- The first version of this package (before it was re-written from scratch) was based
heavily on the excellent
vadimdemedes/tailwind-rn.
- The flexible tw.style()` api was taken outright from
classnames
- TailwindCSS
- Tailwind JIT
- React Native