Skip to content

Nativewind v4 released as a complete rewrite with dynamic styles

updated

Mark Lawlor has announced the release of Nativewind v4. Earlier versions focused on static styling, converting className to style at build time. Version 4 is a complete rewrite that supports highly dynamic styles and the wider Tailwind CSS feature set.

The updated architecture

Nativewind v4 has moved from a Babel plugin to a jsxImportSource transform. Previously, Babel wrapped every component that had a className prop in StyledComponent, or developers wrapped components manually with styled(). With v4, only native components such as <View/> and <Text/> are wrapped. The className prop stays accessible inside components, which allows third-party class management libraries such as tailwind-variants, classnames, clsx and cva.

New features

  • CSS Variables: custom properties can be defined in the theme, inline via vars(), through a plugin, or in CSS, including dark mode media queries.
  • Animations and transitions (experimental): Tailwind CSS animation and transition classes plus custom keyframes, powered by react-native-reanimated. Animated versions of components are created automatically.
  • Groups: support for group and group/<name>.
  • Container queries: available via the official TailwindCSS Container Queries plugin and a subset of the spec in CSS. container-type and style-based queries are not supported.
  • Compilation: improved hot reloading, including changes to the tailwind.config.js theme, and a style compiler rewritten with lightningcss.
  • rem support: rem values are inlined by default. This is configurable with inlineNativeRem.
  • Core components: more sensible defaults on native, including mapping some styles to props, for example color on ActivityIndicator.
  • Theme functions: nested functions such as platformSelect, platformColor, pixelRatioSelect and hairlineWidth.
  • React 18 and web: compatibility with Suspense APIs and React Server Components on web, and readiness for React Native Web's upcoming "compiler-less" mode.
  • Custom CSS (experimental): a limited subset of CSS rules and properties, including @apply and media queries.

Breaking changes from v2

  • styled() has been removed, with no official migration path. The post points to tw-classed as a library with a similar API.
  • The CSS specificity algorithm has changed.
  • The default rem value is now 14 instead of 16. Setting inlineNativeRem: 16 restores the previous behavior.
  • The gap- polyfill has been removed in favor of native columnGap and rowGap.
  • setColorScheme and toggleColorScheme throw unless darkMode: 'dark' is set.
  • group-isolate and parent have been superseded by Tailwind groups.
  • divide- and spacing- are temporarily unavailable.
  • NativeWindStyleSheet has been renamed to StyleSheet.
  • There are new fontFamily defaults.
  • pixelRatio and fontScale have been updated, and pixelRatioSelect and fontScaleSelect have been added.
  • The PostCSS plugin and NativeWindStyleSheet.setOutput() have been removed.
  • border-0.5 has been renamed to border-hairline.

Users of the v3 beta also lose the variant API, setVariables(), useUnsafeVariable (replaced by useUnstableNativeVariables), setDirection() and NativeWindStyleSheet.getSSRStyles(). The odd/even/first/last modifiers are temporarily unavailable.

New APIs

  • remapProps maps style props to className props, for example on FlatList.
  • cssInterop marks a component as a primitive with dynamic style logic.
  • vars() creates inline CSS Variables that are shared with all children through React Context.

Example

// There is no need to wrap this component! `className` is accessible inside the component!
export function MyText({ className, ...props }: TextProps) {
  return <Text className={`text-black ${className}`} {...props} />;
}

Source: www.nativewind.dev