1---
2name: expo-tailwind-setup
3description: Set up Tailwind CSS v4 in Expo with react-native-css and NativeWind v5 for universal styling
4version: 1.0.0
5license: MIT
6---
7 
8# Tailwind CSS Setup for Expo with react-native-css
9 
10This guide covers setting up Tailwind CSS v4 in Expo using react-native-css and NativeWind v5 for universal styling across iOS, Android, and Web.
11 
12## Overview
13 
14This setup uses:
15 
16- **Tailwind CSS v4** - Modern CSS-first configuration
17- **react-native-css** - CSS runtime for React Native
18- **NativeWind v5** - Metro transformer for Tailwind in React Native
19- **@tailwindcss/postcss** - PostCSS plugin for Tailwind v4
20 
21## Installation
22 
23```bash
24# Install dependencies
25npx expo install tailwindcss@^4 [email protected] [email protected] @tailwindcss/postcss tailwind-merge clsx
26```
27 
28Add resolutions for lightningcss compatibility:
29 
30```json
31// package.json
32{
33  "resolutions": {
34    "lightningcss": "1.30.1"
35  }
36}
37```
38 
39- autoprefixer is not needed in Expo because of lightningcss
40- postcss is included in expo by default
41 
42## Configuration Files
43 
44### Metro Config
45 
46Create or update `metro.config.js`:
47 
48```js
49// metro.config.js
50const { getDefaultConfig } = require("expo/metro-config");
51const { withNativewind } = require("nativewind/metro");
52 
53/** @type {import('expo/metro-config').MetroConfig} */
54const config = getDefaultConfig(__dirname);
55 
56module.exports = withNativewind(config, {
57  // inline variables break PlatformColor in CSS variables
58  inlineVariables: false,
59  // We add className support manually
60  globalClassNamePolyfill: false,
61});
62```
63 
64### PostCSS Config
65 
66Create `postcss.config.mjs`:
67 
68```js
69// postcss.config.mjs
70export default {
71  plugins: {
72    "@tailwindcss/postcss": {},
73  },
74};
75```
76 
77### Global CSS
78 
79Create `src/global.css`:
80 
81```css
82@import "tailwindcss/theme.css" layer(theme);
83@import "tailwindcss/preflight.css" layer(base);
84@import "tailwindcss/utilities.css";
85 
86/* Platform-specific font families */
87@media android {
88  :root {
89    --font-mono: monospace;
90    --font-rounded: normal;
91    --font-serif: serif;
92    --font-sans: normal;
93  }
94}
95 
96@media ios {
97  :root {
98    --font-mono: ui-monospace;
99    --font-serif: ui-serif;
100    --font-sans: system-ui;
101    --font-rounded: ui-rounded;
102  }
103}
104```
105 
106## IMPORTANT: No Babel Config Needed
107 
108With Tailwind v4 and NativeWind v5, you do NOT need a babel.config.js for Tailwind. Remove any NativeWind babel presets if present:
109 
110```js
111// DELETE babel.config.js if it only contains NativeWind config
112// The following is NO LONGER needed:
113// module.exports = function (api) {
114//   api.cache(true);
115//   return {
116//     presets: [
117//       ["babel-preset-expo", { jsxImportSource: "nativewind" }],
118//       "nativewind/babel",
119//     ],
120//   };
121// };
122```
123 
124## CSS Component Wrappers
125 
126Since react-native-css requires explicit CSS element wrapping, create reusable components:
127 
128### Main Components (`src/tw/index.tsx`)
129 
130```tsx
131import {
132  useCssElement,
133  useNativeVariable as useFunctionalVariable,
134} from "react-native-css";
135 
136import { Link as RouterLink } from "expo-router";
137import Animated from "react-native-reanimated";
138import React from "react";
139import {
140  View as RNView,
141  Text as RNText,
142  Pressable as RNPressable,
143  ScrollView as RNScrollView,
144  TouchableHighlight as RNTouchableHighlight,
145  TextInput as RNTextInput,
146  StyleSheet,
147} from "react-native";
148 
149// CSS-enabled Link
150export const Link = (
151  props: React.ComponentProps<typeof RouterLink> & { className?: string }
152) => {
153  return useCssElement(RouterLink, props, { className: "style" });
154};
155 
156Link.Trigger = RouterLink.Trigger;
157Link.Menu = RouterLink.Menu;
158Link.MenuAction = RouterLink.MenuAction;
159Link.Preview = RouterLink.Preview;
160 
161// CSS Variable hook
162export const useCSSVariable =
163  process.env.EXPO_OS !== "web"
164    ? useFunctionalVariable
165    : (variable: string) => `var(${variable})`;
166 
167// View
168export type ViewProps = React.ComponentProps<typeof RNView> & {
169  className?: string;
170};
171 
172export const View = (props: ViewProps) => {
173  return useCssElement(RNView, props, { className: "style" });
174};
175View.displayName = "CSS(View)";
176 
177// Text
178export const Text = (
179  props: React.ComponentProps<typeof RNText> & { className?: string }
180) => {
181  return useCssElement(RNText, props, { className: "style" });
182};
183Text.displayName = "CSS(Text)";
184 
185// ScrollView
186export const ScrollView = (
187  props: React.ComponentProps<typeof RNScrollView> & {
188    className?: string;
189    contentContainerClassName?: string;
190  }
191) => {
192  return useCssElement(RNScrollView, props, {
193    className: "style",
194    contentContainerClassName: "contentContainerStyle",
195  });
196};
197ScrollView.displayName = "CSS(ScrollView)";
198 
199// Pressable
200export const Pressable = (
201  props: React.ComponentProps<typeof RNPressable> & { className?: string }
202) => {
203  return useCssElement(RNPressable, props, { className: "style" });
204};
205Pressable.displayName = "CSS(Pressable)";
206 
207// TextInput
208export const TextInput = (
209  props: React.ComponentProps<typeof RNTextInput> & { className?: string }
210) => {
211  return useCssElement(RNTextInput, props, { className: "style" });
212};
213TextInput.displayName = "CSS(TextInput)";
214 
215// AnimatedScrollView
216export const AnimatedScrollView = (
217  props: React.ComponentProps<typeof Animated.ScrollView> & {
218    className?: string;
219    contentClassName?: string;
220    contentContainerClassName?: string;
221  }
222) => {
223  return useCssElement(Animated.ScrollView, props, {
224    className: "style",
225    contentClassName: "contentContainerStyle",
226    contentContainerClassName: "contentContainerStyle",
227  });
228};
229 
230// TouchableHighlight with underlayColor extraction
231function XXTouchableHighlight(
232  props: React.ComponentProps<typeof RNTouchableHighlight>
233) {
234  const { underlayColor, ...style } = StyleSheet.flatten(props.style) || {};
235  return (
236    <RNTouchableHighlight
237      underlayColor={underlayColor}
238      {...props}
239      style={style}
240    />
241  );
242}
243 
244export const TouchableHighlight = (
245  props: React.ComponentProps<typeof RNTouchableHighlight>
246) => {
247  return useCssElement(XXTouchableHighlight, props, { className: "style" });
248};
249TouchableHighlight.displayName = "CSS(TouchableHighlight)";
250```
251 
252### Image Component (`src/tw/image.tsx`)
253 
254```tsx
255import { useCssElement } from "react-native-css";
256import React from "react";
257import { StyleSheet } from "react-native";
258import Animated from "react-native-reanimated";
259import { Image as RNImage } from "expo-image";
260 
261const AnimatedExpoImage = Animated.createAnimatedComponent(RNImage);
262 
263export type ImageProps = React.ComponentProps<typeof Image>;
264 
265function CSSImage(props: React.ComponentProps<typeof AnimatedExpoImage>) {
266  // @ts-expect-error: Remap objectFit style to contentFit property
267  const { objectFit, objectPosition, ...style } =
268    StyleSheet.flatten(props.style) || {};
269 
270  return (
271    <AnimatedExpoImage
272      contentFit={objectFit}
273      contentPosition={objectPosition}
274      {...props}
275      source={
276        typeof props.source === "string" ? { uri: props.source } : props.source
277      }
278      // @ts-expect-error: Style is remapped above
279      style={style}
280    />
281  );
282}
283 
284export const Image = (
285  props: React.ComponentProps<typeof CSSImage> & { className?: string }
286) => {
287  return useCssElement(CSSImage, props, { className: "style" });
288};
289 
290Image.displayName = "CSS(Image)";
291```
292 
293### Animated Components (`src/tw/animated.tsx`)
294 
295```tsx
296import * as TW from "./index";
297import RNAnimated from "react-native-reanimated";
298 
299export const Animated = {
300  ...RNAnimated,
301  View: RNAnimated.createAnimatedComponent(TW.View),
302};
303```
304 
305## Usage
306 
307Import CSS-wrapped components from your tw directory:
308 
309```tsx
310import { View, Text, ScrollView, Image } from "@/tw";
311 
312export default function MyScreen() {
313  return (
314    <ScrollView className="flex-1 bg-white">
315      <View className="p-4 gap-4">
316        <Text className="text-xl font-bold text-gray-900">Hello Tailwind!</Text>
317        <Image
318          className="w-full h-48 rounded-lg object-cover"
319          source={{ uri: "https://example.com/image.jpg" }}
320        />
321      </View>
322    </ScrollView>
323  );
324}
325```
326 
327## Custom Theme Variables
328 
329Add custom theme variables in your global.css using `@theme`:
330 
331```css
332@layer theme {
333  @theme {
334    /* Custom fonts */
335    --font-rounded: "SF Pro Rounded", sans-serif;
336 
337    /* Custom line heights */
338    --text-xs--line-height: calc(1em / 0.75);
339    --text-sm--line-height: calc(1.25em / 0.875);
340    --text-base--line-height: calc(1.5em / 1);
341 
342    /* Custom leading scales */
343    --leading-tight: 1.25em;
344    --leading-snug: 1.375em;
345    --leading-normal: 1.5em;
346  }
347}
348```
349 
350## Platform-Specific Styles
351 
352Use platform media queries for platform-specific styling:
353 
354```css
355@media ios {
356  :root {
357    --font-sans: system-ui;
358    --font-rounded: ui-rounded;
359  }
360}
361 
362@media android {
363  :root {
364    --font-sans: normal;
365    --font-rounded: normal;
366  }
367}
368```
369 
370## Apple System Colors with CSS Variables
371 
372Create a CSS file for Apple semantic colors:
373 
374```css
375/* src/css/sf.css */
376@layer base {
377  html {
378    color-scheme: light;
379  }
380}
381 
382:root {
383  /* Accent colors with light/dark mode */
384  --sf-blue: light-dark(rgb(0 122 255), rgb(10 132 255));
385  --sf-green: light-dark(rgb(52 199 89), rgb(48 209 89));
386  --sf-red: light-dark(rgb(255 59 48), rgb(255 69 58));
387 
388  /* Gray scales */
389  --sf-gray: light-dark(rgb(142 142 147), rgb(142 142 147));
390  --sf-gray-2: light-dark(rgb(174 174 178), rgb(99 99 102));
391 
392  /* Text colors */
393  --sf-text: light-dark(rgb(0 0 0), rgb(255 255 255));
394  --sf-text-2: light-dark(rgb(60 60 67 / 0.6), rgb(235 235 245 / 0.6));
395 
396  /* Background colors */
397  --sf-bg: light-dark(rgb(255 255 255), rgb(0 0 0));
398  --sf-bg-2: light-dark(rgb(242 242 247), rgb(28 28 30));
399}
400 
401/* iOS native colors via platformColor */
402@media ios {
403  :root {
404    --sf-blue: platformColor(systemBlue);
405    --sf-green: platformColor(systemGreen);
406    --sf-red: platformColor(systemRed);
407    --sf-gray: platformColor(systemGray);
408    --sf-text: platformColor(label);
409    --sf-text-2: platformColor(secondaryLabel);
410    --sf-bg: platformColor(systemBackground);
411    --sf-bg-2: platformColor(secondarySystemBackground);
412  }
413}
414 
415/* Register as Tailwind theme colors */
416@layer theme {
417  @theme {
418    --color-sf-blue: var(--sf-blue);
419    --color-sf-green: var(--sf-green);
420    --color-sf-red: var(--sf-red);
421    --color-sf-gray: var(--sf-gray);
422    --color-sf-text: var(--sf-text);
423    --color-sf-text-2: var(--sf-text-2);
424    --color-sf-bg: var(--sf-bg);
425    --color-sf-bg-2: var(--sf-bg-2);
426  }
427}
428```
429 
430Then use in components:
431 
432```tsx
433<Text className="text-sf-text">Primary text</Text>
434<Text className="text-sf-text-2">Secondary text</Text>
435<View className="bg-sf-bg">...</View>
436```
437 
438## Using CSS Variables in JavaScript
439 
440Use the `useCSSVariable` hook:
441 
442```tsx
443import { useCSSVariable } from "@/tw";
444 
445function MyComponent() {
446  const blue = useCSSVariable("--sf-blue");
447 
448  return <View style={{ borderColor: blue }} />;
449}
450```
451 
452## Key Differences from NativeWind v4 / Tailwind v3
453 
4541. **No babel.config.js** - Configuration is now CSS-first
4552. **PostCSS plugin** - Uses `@tailwindcss/postcss` instead of `tailwindcss`
4563. **CSS imports** - Use `@import "tailwindcss/..."` instead of `@tailwind` directives
4574. **Theme config** - Use `@theme` in CSS instead of `tailwind.config.js`
4585. **Component wrappers** - Must wrap components with `useCssElement` for className support
4596. **Metro config** - Use `withNativewind` with different options (`inlineVariables: false`)
460 
461## Troubleshooting
462 
463### Styles not applying
464 
4651. Ensure you have the CSS file imported in your app entry
4662. Check that components are wrapped with `useCssElement`
4673. Verify Metro config has `withNativewind` applied
468 
469### Platform colors not working
470 
4711. Use `platformColor()` in `@media ios` blocks
4722. Fall back to `light-dark()` for web/Android
473 
474### TypeScript errors
475 
476Add className to component props:
477 
478```tsx
479type Props = React.ComponentProps<typeof RNView> & { className?: string };
480```
481