{"id":11767,"library":"react-native-css-interop","title":"React Native CSS Interop","description":"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.","status":"active","version":"0.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/marklawlor/nativewind","tags":["javascript","react-native","react","native","theme","style","typescript"],"install":[{"cmd":"npm install react-native-css-interop","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-css-interop","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-css-interop","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"React Native applications require React.","package":"react","optional":false},{"reason":"Core dependency for React Native environment.","package":"react-native","optional":false},{"reason":"Required for animations and transitions, and potentially for certain reactive styles.","package":"react-native-reanimated","optional":false},{"reason":"Often used in conjunction with this library, especially when integrated via NativeWind, for utility-first styling.","package":"tailwindcss"}],"imports":[{"note":"Primary function for 'tagging' custom or third-party components to allow NativeWind's runtime to resolve `className` strings into styles.","wrong":"const cssInterop = require('react-native-css-interop');","symbol":"cssInterop","correct":"import { cssInterop } from 'react-native-css-interop';"},{"note":"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.","wrong":"import withCssInterop from 'react-native-css-interop';","symbol":"withCssInterop","correct":"import { withCssInterop } from 'react-native-css-interop';"},{"note":"Provides a runtime utility for `rem` unit conversion, consistent with web CSS units. Other units like `vw`, `vh`, `vmax`, `vmin` are also available.","symbol":"rem","correct":"import { rem } from 'react-native-css-interop';"}],"quickstart":{"code":"import React from 'react';\nimport { Text, View, StyleSheet } from 'react-native';\nimport { cssInterop } from 'react-native-css-interop';\n\n// Register a custom component to accept className props\ncssInterop(Text, { className: 'style' });\ncssInterop(View, { className: 'style' });\n\n// Assuming you have a global.css file imported somewhere (e.g., via NativeWind setup)\n// which defines .container and .text-style classes\n// import './global.css';\n\nexport default function App() {\n  return (\n    <View className=\"container p-4 bg-blue-500 rounded-lg\">\n      <Text className=\"text-xl font-bold text-white text-center\">\n        Hello, CSS Interop!\n      </Text>\n      <Text className=\"mt-2 text-base text-gray-200\">\n        This component uses CSS classes processed by react-native-css-interop.\n      </Text>\n    </View>\n  );\n}\n\n// Minimal StyleSheet to ensure React Native doesn't complain about missing styles\n// (actual styles would come from your CSS file/Tailwind processing)\nconst baseStyles = StyleSheet.create({\n  container: {\n    // These would be overridden by CSS/Tailwind\n    padding: 16,\n    backgroundColor: 'blue',\n    borderRadius: 8,\n  },\n  'text-xl': {\n    fontSize: 20,\n  },\n  'font-bold': {\n    fontWeight: 'bold',\n  },\n  'text-white': {\n    color: 'white',\n  },\n  'text-center': {\n    textAlign: 'center',\n  },\n  'mt-2': {\n    marginTop: 8,\n  },\n  'text-base': {\n    fontSize: 16,\n  },\n  'text-gray-200': {\n    color: 'lightgray',\n  },\n});\n","lang":"typescript","description":"Demonstrates registering `Text` and `View` components with `cssInterop` to accept `className` props, enabling CSS styling."},"warnings":[{"fix":"Migrate to `SafeAreaView` from `react-native-safe-area-context` or manually register `react-native`'s `SafeAreaView` if still needed: `cssInterop(SafeAreaView, { className: 'style' });`","message":"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.","severity":"breaking","affected_versions":"0.2.3"},{"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.","message":"Version mismatches with peer dependencies like `tailwindcss` and `react-native-reanimated` can lead to styling issues or unexpected behavior.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":">=5.0.0-preview"},{"fix":"Update to `react-native-css-interop@0.2.2` or higher to ensure proper `ref` preservation with React 19.","message":"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.","severity":"gotcha","affected_versions":"<0.2.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"The `react-native-css-interop` library previously automatically registered `SafeAreaView` from `react-native`, triggering this warning in newer React Native versions.","error":"Warning: The 'SafeAreaView' import from 'react-native' is deprecated. Use 'SafeAreaView' from 'react-native-safe-area-context' instead."},{"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'`.","cause":"Missing required peer dependencies for the library to function correctly.","error":"Error: You must install peer dependencies: tailwindcss (expected ~3), react-native-reanimated (expected >=3.6.2)"},{"fix":"Update `react-native-css-interop` to version `0.2.2` or newer to resolve `ref` handling with React 19.","cause":"An issue with `ref` preservation in `react-native-css-interop` affected React 19 users before version `0.2.2`.","error":"Warning: Function components cannot be given refs. Attempts to access this ref will fail. Did you mean to use React.forwardRef()?"},{"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.","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.","error":"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"}],"ecosystem":"npm"}