React Native CSS Interop

0.2.3 · active · verified Sun Apr 19

react-native-css-interop provides a foundational layer for integrating CSS stylesheets into React Native and React Native Web projects. It is a core dependency for libraries like NativeWind, enabling the use of CSS as a styling language, including advanced features like CSS Variables, Viewport Units (rem, vw, vh, vmax, vmin), Media Queries, and Container Queries. The library is not a full CSS specification implementation but offers an opinionated approach to CSS in React Native. The current stable version is 0.2.3, with active maintenance through patch releases. A new major version of NativeWind (v5) is in preview, which renames `react-native-css-interop` to `react-native-css` and shifts it to a peer dependency, indicating a significant architectural change and decoupling for future versions.

Common errors

```
Warning: The 'SafeAreaView' import from 'react-native' is deprecated. Use 'SafeAreaView' from 'react-native-safe-area-context' instead.
```
cause The `react-native-css-interop` library previously automatically registered `SafeAreaView` from `react-native`, triggering this warning in newer React Native versions.

fix Update `react-native-css-interop` to `0.2.3` or higher. If you still need `SafeAreaView` from `react-native`, manually register it using `cssInterop(SafeAreaView, { className: 'style' });` or switch to `react-native-safe-area-context`.
```
Error: You must install peer dependencies: tailwindcss (expected ~3), react-native-reanimated (expected >=3.6.2)
```
cause Missing required peer dependencies for the library to function correctly.

fix Install the specified peer dependencies: `npm install tailwindcss@~3 react-native-reanimated@'>=3.6.2'` or `yarn add tailwindcss@~3 react-native-reanimated@'>=3.6.2'`.
```
Warning: Function components cannot be given refs. Attempts to access this ref will fail. Did you mean to use React.forwardRef()?
```
cause An issue with `ref` preservation in `react-native-css-interop` affected React 19 users before version `0.2.2`.

fix Update `react-native-css-interop` to version `0.2.2` or newer to resolve `ref` handling with React 19.
```
Metro error: Unable to resolve module react-native/Libraries/Utilities/Platform from ...react-native-css-interop/dist/runtime/third-party-libs/react-native-safe-area-context.js
```
cause This error occurs when `react-native-css-interop` struggles to resolve internal React Native modules, often in specific web build environments or with certain Expo/Metro configurations.

fix Ensure `react-native-web` is correctly configured and transpiled. If using Expo, verify your `metro.config.js` and `babel.config.js` are set up as per NativeWind's recommendations, including `transpilePackages`. Downgrading related `nativewind` versions (e.g., to 4.1.7) has been a temporary workaround for some.

Warnings

breaking The `SafeAreaView` import from `react-native` was deprecated and its automatic `cssInterop` registration was removed in version `0.2.3` to avoid deprecation warnings for all users. Users explicitly relying on this for `react-native`'s `SafeAreaView` will need to manage it manually or use `react-native-safe-area-context` which remains supported.
Fix: Migrate to `SafeAreaView` from `react-native-safe-area-context` or manually register `react-native`'s `SafeAreaView` if still needed: `cssInterop(SafeAreaView, { className: 'style' });`
gotcha Version mismatches with peer dependencies like `tailwindcss` and `react-native-reanimated` can lead to styling issues or unexpected behavior.
Fix: Ensure `react-native-reanimated` (>=3.6.2) and `tailwindcss` (~3) are installed and their versions are compatible with `react-native-css-interop`. Use `npm list react-native-css-interop` to check versions.
gotcha The library provides an 'opinionated' view on how React Native projects can work with CSS and is 'not a full implementation of the CSS spec'. This means certain advanced or less common CSS features might not be supported.
Fix: Consult the official documentation or the `nativewind` project (which leverages `react-native-css-interop`) for a detailed list of supported CSS features and any known limitations.
breaking With NativeWind v5 and future versions, `react-native-css-interop` is being renamed to `react-native-css` and transitioned to a peer dependency. This requires separate installation and a potential update to `metro.config.js` with `withReactNativeCSS` and removal from `babel.config.js`.
Fix: For NativeWind v5+ projects, install `react-native-css` separately, update your Metro configuration with `withReactNativeCSS`, and adjust your Babel configuration as per NativeWind v5 migration guides.
gotcha There was a fix for preserving `ref` in React 19 in version `0.2.2`. Users on older versions of `react-native-css-interop` with React 19 might encounter issues related to ref forwarding on functional components.
Fix: Update to `react-native-css-interop@0.2.2` or higher to ensure proper `ref` preservation with React 19.
gotcha The library can generate large cache files (`node_modules/react-native-css-interop/.cache/android.js`) which might significantly slow down app load times, especially for complex Tailwind configurations.
Fix: Monitor cache file sizes and report issues. For `gluestack-ui-v2` users, work is being done on a `tailwind-plugin` to address this. Consider build optimizations if affected.

Install

npm install react-native-css-interop npm
yarn add react-native-css-interop yarn
pnpm add react-native-css-interop pnpm

Imports

cssInterop
wrong:
```
const cssInterop = require('react-native-css-interop');
```
correct:
```
import { cssInterop } from 'react-native-css-interop';
```
Primary function for 'tagging' custom or third-party components to allow NativeWind's runtime to resolve `className` strings into styles.
withCssInterop
wrong:
```
import withCssInterop from 'react-native-css-interop';
```
correct:
```
import { withCssInterop } from 'react-native-css-interop';
```
A higher-order component alternative to `cssInterop` for applying interoperability to components. This is not explicitly in the provided text but is a common pattern for interop libraries and is found in the project's source.
rem
```
import { rem } from 'react-native-css-interop';
```
Provides a runtime utility for `rem` unit conversion, consistent with web CSS units. Other units like `vw`, `vh`, `vmax`, `vmin` are also available.

Quickstart

Demonstrates registering `Text` and `View` components with `cssInterop` to accept `className` props, enabling CSS styling.

import React from 'react';
import { Text, View, StyleSheet } from 'react-native';
import { cssInterop } from 'react-native-css-interop';

// Register a custom component to accept className props
cssInterop(Text, { className: 'style' });
cssInterop(View, { className: 'style' });

// Assuming you have a global.css file imported somewhere (e.g., via NativeWind setup)
// which defines .container and .text-style classes
// import './global.css';

export default function App() {
  return (
    <View className="container p-4 bg-blue-500 rounded-lg">
      <Text className="text-xl font-bold text-white text-center">
        Hello, CSS Interop!
      </Text>
      <Text className="mt-2 text-base text-gray-200">
        This component uses CSS classes processed by react-native-css-interop.
      </Text>
    </View>
  );
}

// Minimal StyleSheet to ensure React Native doesn't complain about missing styles
// (actual styles would come from your CSS file/Tailwind processing)
const baseStyles = StyleSheet.create({
  container: {
    // These would be overridden by CSS/Tailwind
    padding: 16,
    backgroundColor: 'blue',
    borderRadius: 8,
  },
  'text-xl': {
    fontSize: 20,
  },
  'font-bold': {
    fontWeight: 'bold',
  },
  'text-white': {
    color: 'white',
  },
  'text-center': {
    textAlign: 'center',
  },
  'mt-2': {
    marginTop: 8,
  },
  'text-base': {
    fontSize: 16,
  },
  'text-gray-200': {
    color: 'lightgray',
  },
});

view raw JSON →