Migrate from v4

Migration steps

The simplest way to migrate from Nativewind v4 -> Nativewindv5 is to follow the installation steps again.

Once completed, the only additional step is to remove nativewind from your babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
-      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
-      "nativewind/babel",
+      "babel-preset-expo",
    ],
  };
};

You should now be running Nativewind v5 🎉 If you are running into issues, here are some common steps that may have been overlooked:

Incorrect CSS atRules

Ensure you updated to the new atRules in your CSS file

- @tailwind base;
- @tailwind components;
- @tailwind utilities;
 
+ @import "tailwindcss/theme.css" layer(theme);
+ @import "tailwindcss/preflight.css" layer(base);
+ @import "tailwindcss/utilities.css";
+
+ @import "nativewind/theme";

Metro config

The withNativewind function no longer requires a second argument. Please note that, while withNativeWind was renamed to withNativewind, either will work.

- module.exports = withNativeWind(config, { input: './global.css' })
+ module.exports = withNativewind(config);

PostCSS config

Ensure that the postcss.config.mjs file was created!

JSX transform errors

Ensure that you removed nativewind from your babel config. You will most likely need to clear the Metro cache by running npx expo start --clear.

Breaking Changes & Prerequisites

Before upgrading to Nativewind v5, your project must meet the following version requirements:

Tailwind CSS v4.1+

Nativewind v5 is built on top of Tailwind v4.1+. You must upgrade your Tailwind configuration and tooling, accordingly.

React Native 0.81+

React Native 0.81 introduces architectural changes that Nativewind v5 relies on, including improvements to the StyleSheet and layout engines.

React Native New Architecture

A number of styles require the new architecture.

React Native Reanimated v4+

Nativewind v5 uses internal features that depend on Reanimated v4+. Ensure your project uses this version to avoid runtime crashes or build issues.

React Native CSS

Nativewind previously used a transient dependency on a library called react-native-css-interop. This library has been renamed to react-native-css, has been moved to be a peer dependency, and will require separate installation.

Nativewind will no longer be tied to a specific version of react-native-css and the two libraries can be updated individually.

Breaking changes

Tailwind CSS changes

Please ensure you are familiar with the Tailwind CSS upgrade guide. It has a number of breaking changes, renamed styles and deprecations.

Classname changes

Tailwind v4 changed the standard for its classnames. As such, these Nativewind classes have also been renamed:

• elevation-sm has been renamed to elevation-xs
• elevation has been renamed to elevation-sm

Animation changes

Nativewind has switched from using a custom animation engine to Reanimated CSS animations. You may find there are implementation differences between the two engines.

JavaScript Theme Functions

The JavaScript theme functions have been removed and replaced with CSS equivalent functions. Please see the Tailwind CSS functions and directives documentation for more information.

shadow-*

The shadow-* classes now use boxShadow style. Previously they used shadowColor, shadowOffset, shadowOpacity and shadowRadius. There may be a visual difference.

Line Height

Line height numeric values are parsed as if they had the em unit. Previously they were parsed as a unit-less value. To migrate, simply divide the old value by the font-size.

rem

rem is no longer exported and cannot be changed at runtime. If you require Tailwind CSS to dynamically change values, you should update your theme to use a CSS variable instead of rem

Dynamic mapping modifier

The dynamic mapping modifier has been renamed to @prop.

- {}-[inputColor]:color-black
+ @prop-[inputColor]:color-black

Deprecations

Nativewind v5 preserves its existing API. Your usage of:

• className
• styled

...will continue to work without modification.

However, several features are being deprecated and will emit runtime warnings during development. These features will be removed in a future major release.

However, there will be a number of breaking changes to how Nativewind functions and its configuration file that may affect you.

JSX Transform → Replaced by Import Rewrites

Nativewind v5 removes the JSX transform that previously injected Tailwind support into individual JSX elements. This has been replaced by a new import rewrite system.

This does not require any configuration change, but may affect your app if you are performing your own import rewrites. Previously Nativewind would change this code:

import { View, Text } from "react-native";
 
<View className="bg-red-500 p-4">
  <Text className="text-white">Hello</Text>
</View>;

Now the import will be rewritten to import { View, Text } from 'react-native-css/react-native'

The move to import rewrites is driven by a broader shift in the React Native ecosystem of publishing compiled libraries. Nativewind previously took advantage of the fact that libraries were always compiled locally, which allowed us to override the jsxImportSource. When libraries are compiled externally, their JSX is already transformed. The new shift to import rewrites is similar to how existing libraries such as react-native-web work.

cssInterop / remapProps → Replaced by styled()

The cssInterop and remapProps APIs are deprecated and have been replaced with a unified styled API. It accepts the same options as cssInterop/remapProps and returns the same component. The remapProps mode is available via a new 3rd parameter:

// Same as cssInterop()
styled(View, { className: "style" });
 
// Same as remapProps()
styled(View, { className: "style" }, { passThrough: true });

By default styled() enables the transform globally for that component, but this can be disabled by setting global to false:

const MyComponent = styled(View, { className: "style" }, { global: false });

Native functions

The nativewind/theme export has been removed. You can now access these functions as CSS functions.

platformColor

platformColor() is available as a CSS function:

@theme {
  --color-error: platformColor(systemRed, red);
}

hairlineWidth

hairlineWidth() is available as a CSS function:

@theme {
  --spacing-hairline: hairlineWidth();
}

pixelRatio

pixelRatio() is available as a CSS function:

@theme {
  --spacing-doublePixelRatio: calc(pixelRatio(2) * 2);
}

fontScale

fontScale() is available as a CSS function:

@theme {
  --spacing-doubleFontScale: calc(fontScale(2) * 2);
}

getPixelSizeForLayoutSize

getPixelSizeForLayoutSize() is available as a CSS function:

@theme {
  --spacing-custom: getPixelSizeForLayoutSize(42);
}

roundToNearestPixel

roundToNearestPixel() is available as a CSS function:

@theme {
  --spacing-custom: roundToNearestPixel(calc(10 / 3));
}

platformSelect

Now use a media query that sets the platform as the media type:

@theme {
  --color-error: var(--my-color, green);
}
 
@media ios {
  :root {
    --my-color: red;
  }
}
 
@media android {
  :root {
    --my-color: blue;
  }
}

pixelRatioSelect / fontScaleSelect

Now use a media query:

@theme {
  --spacing-custom-pixel: 11;
  --spacing-custom-font: 11;
}
 
@media (pixelRatio() > 2) {
  :root {
    --spacing-custom-pixel: 3;
  }
}
 
@media (fontScale() > 2) {
  :root {
    --spacing-custom-font: 3;
  }
}

New CSS Features

Nativewind v5 adds support for the new React Native styling features:

• position: static (Tailwind) (Yoga)
• align-content: space-evenly (Tailwind) (Yoga)
• filter() (Tailwind) (React Native)
• backgroundImage() (Tailwind) (gradients only)
• box-sizing (Tailwind)
• display: contents (Tailwind)