{"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,"search_vec":"'0.2.3':86 'activ':88 'advanc':45 'approach':75 'architectur':125 'chang':126 'contain':60 'core':29 'css':3,8,16,39,48,68,77,108,114 'current':82 'decoupl':128 'depend':30,121 'enabl':35 'featur':46 'foundat':12 'full':67 'futur':130 'implement':70 'includ':44 'indic':122 'integr':15 'interop':4,9,109 'javascript':132 'languag':43 'layer':13 'librari':32,63 'like':33,47 'mainten':89 'major':95 'media':57 'nativ':2,7,20,23,80,107,113,135,137 'nativewind':34,98 'new':94 'offer':72 'opinion':74 'patch':91 'peer':120 'preview':102 'project':25 'provid':10 'queri':58,61 'react':1,6,19,22,79,106,112,134,136 'react-nat':133 'react-native-css':111 'react-native-css-interop':5,105 'releas':92 'rem':52 'renam':104 'shift':116 'signific':124 'specif':69 'stabl':83 'style':42,139 'stylesheet':17 'theme':138 'typescript':140 'unit':51 'use':37 'v5':99 'variabl':49 'version':84,96,131 'vh':54 'viewport':50 'vmax':55 'vmin':56 'vw':53 'web':24","created_at":"2026-04-19T13:39:41.917532+00:00","updated_at":"2026-04-19T13:39:41.917532+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://nativewind.dev","github":"https://github.com/nativewind/nativewind","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/react-native-css-interop","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}