Registry / web-framework / react-native-css-interop

react-native-css-interop

library0.2.3jsnpmunverified

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.

web-framework serialization

npm install react-native-css-interop

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-CSS-I

react-native-css-interop

web-frameworkjavascriptv0.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cssInterop

✓ import { cssInterop } from 'react-native-css-interop';

✗ const cssInterop = require('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

✓ import { withCssInterop } from 'react-native-css-interop';

✗ 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.

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', }, });

Debug

Known issues

breakingThe `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' });`

affects: 0.2.3

gotchaVersion 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.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

breakingWith 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.

affects: >=5.0.0-preview

gotchaThere 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.

affects: <0.2.2

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

Warning: The 'SafeAreaView' import from 'react-native' is deprecated. Use 'SafeAreaView' from 'react-native-safe-area-context' instead.

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)

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()?

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

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.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

reactrequiredReact Native applications require React.

react-nativerequiredCore dependency for React Native environment.

react-native-reanimatedrequiredRequired for animations and transitions, and potentially for certain reactive styles.

tailwindcssrequiredOften used in conjunction with this library, especially when integrated via NativeWind, for utility-first styling.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/nativewind/nativewind ↗

packagehttps://www.npmjs.com/package/react-native-css-interop ↗

homepagehttps://nativewind.dev ↗