DOCSEARCHbyAlgolia
Submit Docs

NativeWind Documentation

website·Indexed 35 days ago

https://www.nativewind.dev

NativeWind allows the use of Tailwind CSS v3 for styling React Native applications. It provides a common language between CSS and React Native, featuring a specificity model aligned with CSS rules, support for dark mode, responsive design, and pseudo-classes like :hover and :focus. The library includes APIs such as cssInterop, remapProps, and withNativeWind for Metro configuration, as well as hooks like useColorScheme() and vars() for CSS variable management.

Tokens
39.5K
Snippets
252
Records
339
Agent score
71%

What's inside NativeWind

  1. Overview of Nativewind for React Native

    Nativewind allows developers to use Tailwind CSS v3 to style React Native components. It provides a consistent styling experience across platforms by using the most efficient engine for each: CSS StyleSheet for web and StyleSheet.create for native platforms. At build time, it compiles Tailwind styles into native objects and handles conditional logic (hover, focus, active). On the web, it acts as a polyfill to add className support to React Native Web, enabling Server Side Rendering (SSR) and better initial load performance by reusing the Tailwind CSS stylesheet.

  2. Understand how NativeWind applies Tailwind CSS classes in React Native

    NativeWind accepts all Tailwind CSS classes, but it only applies styles that are supported by the target platform. For example, layout utilities like grid will function on the web but will be ignored on native platforms because React Native does not support CSS Grid.

  3. Implement style transitions in NativeWind

    NativeWind uses react-native-reanimated to power transitions, allowing for smooth interpolation between style values when classes change. Transitions can be triggered by class changes during a rerender, pseudo-class interactions (such as :active), or combined with group parent states. Supported transitions include numeric properties (e.g., width, height, opacity) and color interpolation.

  4. Understand NativeWind's relationship with Tailwind CSS

    NativeWind is built upon the Tailwind CSS style language, meaning the core concepts of Tailwind CSS apply directly to NativeWind. Developers should follow Tailwind's official guides for Utility-First Fundamentals, Reusing Styles, and Adding Custom Styles to effectively use NativeWind. Because styles are generated via the Tailwind CLI, the full Tailwind CSS language and compiler options are available for web platforms.

  5. Load custom fonts at runtime with useFonts

    If you cannot use the app.json plugin, you can load fonts dynamically using the useFonts hook from expo-font. You must handle the loading state (e.g., returning null) until the fonts are ready.
    import { useFonts } from "expo-font";

export default function App() {
  const [fontsLoaded] = useFonts({
    "Inter-Regular": require("./assets/fonts/Inter-Regular.otf"),
    "Inter-Bold": require("./assets/fonts/Inter-Bold.otf"),
  });

  if (!fontsLoaded) return null;

  return <>{/* your app */}</>;
}

  6. Style components using data attribute selectors

    You can style components based on data attributes using [data-*] selectors. This relies on React Native Web's dataSet prop. It supports both presence checks ([data-test]) and value equality checks ([data-test='value']).
    import { View, Text } from "react-native";

function StatusBadge({ active }) {
  return (
    <View
      className="[&[data-active]]:bg-green-500 [&[data-active='false']]:bg-gray-500"
      {...{ dataSet: { active: active } }}
    >
      <Text>Status</Text>
    </View>
  );
}

  7. Apply rotation transforms with NativeWind

    NativeWind supports rotation using standard Tailwind CSS classes. You can use theme-defined values via rotate-{n} or arbitrary values via rotate-[n].

    Critical Requirement: When using arbitrary values or defining rotation in your theme, you must explicitly include the deg unit (e.g., rotate-[90deg]). React Native only supports deg as a unit for rotation.

    // Using a theme value
<View className="rotate-45" />

// Using an arbitrary value (must include 'deg')
<View className="rotate-[90deg]" />

  8. Install NativeWind in a framework-less React Native project

    To use NativeWind in a project initialized with the React Native Community CLI, install the core library along with its required peer dependencies: tailwindcss, react-native-reanimated, and react-native-safe-area-context. After installation, run npx pod-install to complete the setup for react-native-reanimated.
    # Using npm
npm install nativewind@4.2.7 react-native-reanimated react-native-safe-area-context
npm install --save-dev tailwindcss@^3.4.17 prettier-plugin-tailwindcss@^0.5.11

# Using yarn
yarn add nativewind@4.2.7 react-native-reanimated react-native-safe-area-context
yarn add --dev tailwindcss@^3.4.17 prettier-plugin-tailwindcss@^0.5.11

# Using pnpm
pnpm add nativewind@4.2.7 react-native-reanimated react-native-safe-area-context
pnpm add --save-dev tailwindcss@^3.4.17 prettier-plugin-tailwindcss@^0.5.11

# Using bun
bun add nativewind@4.2.7 react-native-reanimated react-native-safe-area-context
bun add --dev tailwindcss@^3.4.17 prettier-plugin-tailwindcss@^0.5.11

# Finalize iOS dependencies
npx pod-install

  9. Style SVG stroke width with NativeWind

    NativeWind supports stroke width utilities for SVG elements. You can use theme-based values with stroke-{n} or arbitrary values with stroke-[n]. Because React Native does not have built-in SVG components, you must use a library like react-native-svg and wrap the components with cssInterop to map Tailwind classes to native SVG props (such as strokeWidth).
    import React from 'react';
import { View } from 'react-native';
import Svg, { Circle, Rect } from 'react-native-svg';
import { cssInterop } from 'nativewind';

// Map className to style and specific native props
cssInterop(Svg, {
  className: {
    target: "style",
    nativeStyleToProp: { width: true, height: true }
  },
});
cssInterop(Circle, {
  className: {
    target: "style",
    nativeStyleToProp: { width: true, height: true, stroke: true, strokeWidth: true, fill: true }
  },
});
cssInterop(Rect, {
  className: {
    target: "style",
    nativeStyleToProp: { width: true, height: true, stroke: true, strokeWidth: true, fill: true }
  },
});

export function SvgExample () {
  return (
    <View className="inset-0 items-center content-center">
      <Svg className="h-1/2 w-1/2" viewBox="0 0 100 100" >
        {/* stroke-2 applies the stroke width */}
        <Circle cx="50" cy="50" r="45" className="stroke-blue-500 stroke-2 fill-green-500" />
        <Rect x="15" y="15" className="w-16 h-16 stroke-red-500 stroke-2 fill-yellow-500" />
      </Svg>
    </View>
  );
}

  10. Scale text dynamically based on screen width

    Since NativeWind does not support media queries on :root, dynamic text scaling is achieved by combining a CSS variable, a wrapper class for media queries, and an arbitrary value utility class. Define the variable within a class in your CSS, then apply both the wrapper class and the variable reference to your components.
    /* global.css */
@media (min-width: 640px) {
  .text-root {
    --font-size-dynamic: 16px;
  }
}

@media (min-width: 768px) {
  .text-root {
    --font-size-dynamic: 18px;
  }
}
    /* App.tsx */
export default function App() {
  return (
    <Text className="text-root">
      <Text className="text-[--font-size-dynamic]">I scale with screen width</Text>
    </Text>
  );
}

  11. Implement automatic dark mode using system preferences

    By default, Nativewind follows the device's system appearance (light, dark, or automatic). To read the current system preference, use the colorScheme value returned from the useColorScheme hook. This value automatically updates when the system appearance changes. For Expo apps, ensure userInterfaceStyle is set to automatic in app.json for this to function correctly.

  12. Configure Safe Area Insets for Web

    On web, NativeWind uses the CSS env() function, requiring no extra setup for basic safe area utilities. However, h-screen-safe and min-h-screen-safe may not function correctly in Google Chrome. To fix this, apply height: -webkit-fill-available to the html, body, and root elements in your global CSS.
    @tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  html {
    height: -webkit-fill-available;
  }

  body {
    height: -webkit-fill-available;
  }

  #root {
    height: -webkit-fill-available;
  }
}