Skip to main content

​
Overview

NativeWind uses Tailwind CSS v4, which introduces a simplified configuration approach using CSS-based theme configuration instead of traditional JavaScript config files. This provides better type safety, performance, and integration with your styles.

​
Basic Configuration

NativeWind requires two key configuration files:

​
PostCSS Configuration

Create a postcss.config.mjs file in your project root:
postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

​
CSS Entry File

Create a global CSS file (e.g., global.css) that imports Tailwind layers:
global.css
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";

/* Import NativeWind theme customizations */
@import "nativewind/theme";
The order of imports matters. The theme layer must come first, followed by preflight (base styles), and then utilities.

​
Theme Customization

With Tailwind CSS v4, you customize your theme using the @theme directive in your CSS files:

​
Custom Theme File

Create a theme.css file:
theme.css
@plugin "nativewind";

@theme {
  /* Custom spacing values */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  
  /* Custom colors */
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  --color-accent: #ec4899;
  
  /* Custom elevation (React Native shadows) */
  --elevation-xs: 1;
  --elevation-sm: 3;
  --elevation-md: 6;
  --elevation-lg: 8;
  --elevation-xl: 13;
  --elevation-2xl: 24;
  --elevation-none: 0;
}

import { View, Text } from "react-native";
import "./global.css";

export default function App() {
  return (
    <View className="p-lg bg-primary">
      <Text className="text-white elevation-md">
        Custom themed component
      </Text>
    </View>
  );
}

​
Platform-Specific Configuration

NativeWind allows you to define platform-specific values using media queries:

​
Platform-Specific Fonts

theme.css
:root {
  @media ios {
    --font-sans: System;
    --font-serif: Georgia;
    --font-mono: Menlo;
  }

  @media android {
    --font-sans: SystemAndroid;
    --font-serif: sans-serif;
    --font-mono: monospace;
  }
}

​
Platform-Specific Utilities

You can create utilities that behave differently on each platform:
theme.css
@media ios {
  .shadow-default {
    --elevation: 3;
  }
}

@media android {
  .shadow-default {
    --elevation: 6;
  }
}

​
Custom Utilities

Create custom utility classes using the @utility directive:

​
Color Utilities

theme.css
@utility color-* {
  color: --value(--color-*);
}

@utility tint-* {
  -rn-tint: --value(--color-*);
  @prop -rn-tint tint;
}
Usage: 
<Text className="color-primary">Colored text</Text>
<Image className="tint-secondary" source={icon} />

​
React Native-Specific Utilities

NativeWind includes utilities for React Native-specific props:
theme.css
/* Elevation (Android shadow) */
@utility elevation-* {
  -rn-elevation: --value(--elevation-*);
}

/* Android ripple effects */
@utility ripple-* {
  -rn-ripple-style: --value("borderless");
  -rn-ripple-color: --value(--color-*);
}

@utility ripple-* {
  -rn-ripple-radius: --value(integer);
}

@utility ripple-foreground {
  -rn-ripple-foreground: "foreground";
}

/* Corner shapes (iOS) */
@utility corner-* {
  corner-shape: --value("rounded", "squircle");
}
Custom utilities that use -rn- prefixed properties are React Native-specific and won’t work on web platforms.

​
Custom Variants

Define custom variants for conditional styling:
theme.css
@custom-variant ios (@media ios);
@custom-variant android (@media android);
@custom-variant native (@media native);
@custom-variant tv (@media (display-mode: tv));
@custom-variant web (@supports selector(div > div));
Usage: 
<View className="ios:bg-blue-500 android:bg-green-500">
  <Text className="native:text-lg web:text-xl">Platform-specific styling</Text>
</View>

​
Line Height Override

React Native requires unitless values for line-height. NativeWind overrides the default Tailwind behavior:
theme.css
/**
 * Override leading-* utility to return unitless values
 * React Native requires line-height without units
 */
@utility leading-* {
  line-height: calc(var(--spacing) / 1rem * --value(integer));
}
This allows you to use standard Tailwind classes like leading-relaxed or leading-tight in React Native.

​
Plugin Integration

Load the NativeWind plugin in your theme file:
theme.css
@plugin "nativewind";

@theme {
  /* Your theme configuration */
}
For local development, reference the plugin by path:
theme.css
@plugin "./node_modules/nativewind/dist/module/plugin.js";

​
Third-Party Plugins

NativeWind supports Tailwind CSS plugins. For example, using the safe area plugin:
theme.css
@plugin "nativewind";
@import "tailwindcss-safe-area";

@theme {
  /* Your configuration */
}
This enables utilities like pt-safe and pb-safe for handling device safe areas.

​
Complete Example

Here’s a comprehensive theme configuration: 
@plugin "nativewind";
@import "tailwindcss-safe-area";

@theme {
  /* Brand colors */
  --color-brand-primary: #3b82f6;
  --color-brand-secondary: #8b5cf6;
  --color-brand-accent: #ec4899;
  
  /* Elevation values */
  --elevation-xs: 1;
  --elevation-sm: 3;
  --elevation-md: 6;
  --elevation-lg: 8;
  --elevation-xl: 13;
  --elevation-2xl: 24;
  --elevation-none: 0;
  
  /* Custom spacing */
  --spacing-card: 16px;
  --spacing-section: 32px;
}

/* Platform-specific fonts */
:root {
  @media ios {
    --font-sans: System;
    --font-serif: Georgia;
    --font-mono: Menlo;
  }

  @media android {
    --font-sans: SystemAndroid;
    --font-serif: sans-serif;
    --font-mono: monospace;
  }
}

/* Custom utilities */
@utility leading-* {
  line-height: calc(var(--spacing) / 1rem * --value(integer));
}

@utility elevation-* {
  -rn-elevation: --value(--elevation-*);
}

@utility ripple-* {
  -rn-ripple-color: --value(--color-*);
}

/* Custom variants */
@custom-variant ios (@media ios);
@custom-variant android (@media android);
@custom-variant native (@media native);
@custom-variant tv (@media (display-mode: tv));
@custom-variant web (@supports selector(div > div));

​
Best Practices

Use CSS Variables

Define reusable values in the @theme block for consistency across your app

Platform Detection

Use @media queries for platform-specific styling instead of runtime checks

Type Safety

CSS-based configuration provides better autocomplete in modern editors

Performance

Build-time processing means zero runtime overhead for your theme

​
Migration from v3

If you’re migrating from NativeWind v3, note these key differences:
  • No more tailwind.config.js - use CSS @theme instead
  • Plugin registration happens in CSS with @plugin
  • Custom utilities use @utility directive
  • Platform variants are defined with @custom-variant
For a complete migration guide, see the Migration Documentation.