v5 Migration Guide

Welcome to the official upgrade guide for Nativewind v5. This release introduces several foundational changes that align Nativewind with the future of React Native while maintaining backward compatibility with the core API.

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 CSS v4.1+. You must upgrade your Tailwind configuration and tooling accordingly.

React Native 0.79+

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

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 and moved to a peerDependency and will require installation.

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

No Runtime Breaking Changes — But Some 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 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 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 })

shadow-* → box-shadow

Previously the shadow-* utilities mapped to the React Native shadow props. They will now map to a box shadow style.

nativewind/theme → Replaced by custom CSS

If you are using the new Tailwind CSS v4 CSS config file, you are unable to import the nativewind/theme functions. These have been replaced with custom CSS.

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)