Nativewind v5

https://www.nativewind.dev/v5
Admin
Nativewind v5 is a pre-release version of a library that allows developers to use Tailwind CSS to...
Tokens:103,379
Snippets:806
Trust Score:8.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install expo-font

Source: https://www.nativewind.dev/v5/guides/custom-fonts

Install the expo-font package using bun.

```bash
bun add expo-font
```

--------------------------------

### Install @expo/metro-config for Framework-less React Native

Source: https://www.nativewind.dev/v5/llms-full.txt

Install @expo/metro-config for framework-less React Native projects. After installation, follow the Expo installation guide but replace `expo/metro-config` with `@expo/metro-config` in the Metro config file.

```bash
npm install @expo/metro-config
```

```bash
yarn add @expo/metro-config
```

```bash
pnpm add @expo/metro-config
```

```bash
bun add @expo/metro-config
```

--------------------------------

### Install and configure expo-font in app.json

Source: https://www.nativewind.dev/v5/llms-full.txt

Install expo-font and configure it in app.json to load fonts at build time. This approach makes fonts available immediately without a loading state.

```bash
bun add expo-font
```

```json
{
  "expo": {
    "plugins": [
      [
        "expo-font",
        {
          "fonts": [
            "./assets/fonts/Inter-Regular.otf",
            "./assets/fonts/Inter-Bold.otf",
            "./assets/fonts/Inter-Italic.otf",
            "./assets/fonts/Inter-BoldItalic.otf",
            "./assets/fonts/Inter-Medium.otf",
            "./assets/fonts/Inter-SemiBold.otf"
          ]
        }
      ]
    ]
  }
}
```

--------------------------------

### Install NativeWind and react-native-css with npm

Source: https://www.nativewind.dev/v5/getting-started/installation

Install the exact RC pair together. NativeWind 5.0.0-rc.0 requires react-native-css 3.1.0-rc.0; do not combine the RC with an unpinned engine.

```bash
npm install --save-exact nativewind@5.0.0-rc.0 react-native-css@3.1.0-rc.0
```

--------------------------------

### Using platformColor() for platform colors

Source: https://www.nativewind.dev/v5/core-concepts/functions-and-directives

Accesses platform-specific named colors using `platformColor()`. The example uses `systemBlue`.

```css
.system-blue {
  color: platformColor(systemBlue);
}
```

--------------------------------

### Load Tailwind plugins with @plugin

Source: https://www.nativewind.dev/v5/customization/theme

Load Tailwind plugins using @plugin. The example shows loading a local plugin and the tailwindcss-safe-area plugin.

```css
@plugin "./my-plugin.js";
@plugin "tailwindcss-safe-area";
```

--------------------------------

### Combining pseudo-classes

Source: https://www.nativewind.dev/v5/core-concepts/states

Multiple pseudo-classes can be combined; all conditions must be met for the styles to apply. This example combines `hover:`, `active:`, and `focus:` on a `TextInput`.

```tsx
<TextInput className="hover:active:focus:border-blue-500" />
```

--------------------------------

### Configure Metro with withNativewind

Source: https://www.nativewind.dev/v5/llms-full.txt

Wrap the Metro configuration with withNativewind to enable Nativewind. This is the standard setup for Expo projects.

```tsx
const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");

const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config);
```

--------------------------------

### Restart Metro with expo start --clear

Source: https://www.nativewind.dev/v5/getting-started/troubleshooting

Run this command after changing dependencies or configuration to restart Metro with a cleared cache. This is required for changes to take effect.

```bash
npx expo start --clear
```

--------------------------------

### Initialize Expo project with NativeWind v5

Source: https://www.nativewind.dev/v5/getting-started/installation

Use this command to create a new Expo project pre-configured with NativeWind v5 and Tailwind CSS. Check the generated package versions against the RC target.

```bash
npx rn-new@next --nativewind
```

--------------------------------

### Root layout using ThemeProvider

Source: https://www.nativewind.dev/v5/guides/themes

Imports the global CSS and wraps the Stack navigator with the ThemeProvider, selecting the 'brand' theme.

```tsx
import "../global.css";
import { Stack } from "expo-router";
import { ThemeProvider } from "@/components/ThemeProvider";
 
export default function RootLayout() {
  return (
    <ThemeProvider name="brand">
      <Stack />
    </ThemeProvider>
  );
}
```

--------------------------------

### Install Tailwind CSS and PostCSS dependencies

Source: https://www.nativewind.dev/v5/getting-started/installation

Install Tailwind CSS 4.1.12, @tailwindcss/postcss, postcss, and lightningcss as dev dependencies. Optionally install prettier-plugin-tailwindcss to automatically format Tailwind CSS code.

```bash
npm install --save-dev --save-exact tailwindcss@4.1.12 @tailwindcss/postcss@4.1.12 postcss lightningcss@1.30.1
```

--------------------------------

### Add the nativewind-preview-to-rc migration skill

Source: https://www.nativewind.dev/v5/guides/migrate-from-preview

Adds the migration skill that checks the starting state, including interrupted upgrades, and records remaining verification. Its fixture tests do not replace checks in your application.

```bash
npx skills add nativewind/nativewind --skill nativewind-preview-to-rc
```

--------------------------------

### Define custom utility with @utility

Source: https://www.nativewind.dev/v5/customization/theme

Define custom utilities with @utility. Then use it as className="my-shadow".

```css
@utility my-shadow {
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}
```

--------------------------------

### Test component to verify Nativewind setup

Source: https://www.nativewind.dev/v5/getting-started/installation

Create this App.tsx file to test your Nativewind setup. It imports the global CSS and uses className with Tailwind utility classes to style a centered text. If the styled text appears on a white background, Nativewind is working correctly.

```tsx
import "./global.css"
import { Text, View } from "react-native";
 
export default function App() {
  return (
    <View className="flex-1 items-center justify-center bg-white">
      <Text className="text-xl font-bold text-blue-500">
        Welcome to Nativewind!
      </Text>
    </View>
  );
}
```

--------------------------------

### v5 approach (global.css)

Source: https://www.nativewind.dev/v5/guides/custom-fonts

In v5, fonts are configured in CSS using @theme.

```css
/* v5 approach (global.css) */
@theme {
  --font-inter: "Inter-Regular";
  --font-inter-bold: "Inter-Bold";
}
```

--------------------------------

### Define custom variants with @custom-variant

Source: https://www.nativewind.dev/v5/customization/theme

Define custom variants with @custom-variant. The example shows dark and landscape variants.

```css
@custom-variant dark (@media (prefers-color-scheme: dark));
@custom-variant landscape (@media (orientation: landscape));
```

--------------------------------

### Selection and Placeholder modifiers

Source: https://www.nativewind.dev/v5/core-concepts/states

Use `selection:` to style text selection and `placeholder:` to style placeholder text. This example applies both to a `TextInput`.

```tsx
<TextInput
  className="selection:text-black placeholder:text-gray-400"
  placeholder="Enter text..."
/>
```

--------------------------------

### styled(Component, options?)

Source: https://www.nativewind.dev/v5/llms-full.txt

Creates a wrapper component with className support and optional prop/style mapping. Use for third-party native components that don't pass through the className prop.

```APIDOC
## styled(Component, options?)

### Description
Creates a wrapper component that supports the `className` prop and optionally maps style properties to component props. The original component is unchanged and not globally registered.

### Method
styled

### Endpoint
styled(Component, options?)

### Parameters
#### Arguments
- **Component** (React.ComponentType) - Required - The component to wrap.
- **options** (object) - Optional - Configuration for className mapping and prop forwarding.
  - **className** (object) - Optional - Mapping configuration for the className prop.
    - **target** (string | false) - Optional - The prop name to receive the resolved style object, or `false` to disable style object passing.
    - **nativeStyleMapping** (object) - Optional - Maps style properties to component props. Each key is a style property name, and the value is `true` to pass the style value as a prop with the same name.
  - **passThrough** (boolean) - Optional - When `true`, forwards styles to another styled component. Requires a compatible downstream consumer.

### Request Example
```tsx
import { styled } from "nativewind";
import { ThirdPartyView } from "third-party-library";

const StyledView = styled(ThirdPartyView, { className: "style" });

<StyledView className="bg-blue-500 p-4" />;
```

### Response
#### Success Response
Returns a new wrapper component that accepts `className` and other props, applying the mapped styles.

#### Response Example
```tsx
const StyledComponent = styled(SomeNativeComponent);
<StyledComponent className="bg-blue-500 p-4" />
```

```

--------------------------------

### Disabled and Empty pseudo-classes

Source: https://www.nativewind.dev/v5/core-concepts/states

Use `disabled:` when the component has `disabled={true}` and `empty:` when the component has no children. This example shows a `TextInput` with disabled styles.

```tsx
import { TextInput } from "react-native";
 
function MyInput({ disabled }) {
  return (
    <TextInput
      className="border disabled:opacity-50 disabled:bg-gray-200"
      disabled={disabled}
    />
  );
}
```

--------------------------------

### v4 approach (tailwind.config.js)

Source: https://www.nativewind.dev/v5/guides/custom-fonts

In v4, fonts were configured in JavaScript via tailwind.config.js.

```javascript
// v4 approach (tailwind.config.js)
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        inter: ["Inter-Regular"],
        "inter-bold": ["Inter-Bold"],
      },
    },
  },
};
```

--------------------------------

### LTR and RTL modifiers

Source: https://www.nativewind.dev/v5/core-concepts/states

Use `ltr:` and `rtl:` to apply styles based on text direction. This example applies `text-left` for LTR and `text-right` for RTL.

```tsx
<Text className="ltr:text-left rtl:text-right">
  Direction-aware text
</Text>
```
Tokens:
Raw