{"id":15201,"library":"react-native-unistyles","title":"React Native Unistyles","description":"react-native-unistyles is a high-performance, universal styling solution for React Native, designed to enhance developer experience and application performance across iOS, Android, Web, and Expo environments. It leverages a shared C++ core and JSI bindings, powered by Nitro Modules, to achieve styling without triggering unnecessary re-renders in the React tree. The library is currently stable at version 3.2.3, with a rapid release cadence addressing features and bug fixes. Key differentiators include its unique custom web parser supporting CSS classes and pseudo-classes, tight integration with React Native's Fabric and Shadow Tree for optimal rendering, and significant performance benefits, adding under 0.1ms to StyleSheet processing. It allows developers to share nearly 100% of styles across platforms in a monorepo setup, register multiple themes, and dynamically switch them with a single function call, all without introducing new components into the view hierarchy. This approach ensures a clean and efficient component tree.","status":"active","version":"3.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/jpudysz/react-native-unistyles","tags":["javascript","react-native","ios","android","react-native-web","expo","fabric","typescript"],"install":[{"cmd":"npm install react-native-unistyles","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-unistyles","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-unistyles","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core native module for performance and JSI bindings. Strict version compatibility is required (e.g., Unistyles >=3.2.0 requires Nitro Modules >=0.35.2).","package":"react-native-nitro-modules","optional":false},{"reason":"Recommended for comprehensive edge-to-edge support and system bar management, but optional since v3.1.0. Automatically enabled by Expo SDK 54+.","package":"react-native-edge-to-edge","optional":true},{"reason":"Core React Native framework, required minimum v0.76.0 for Unistyles v3.","package":"react-native","optional":false},{"reason":"React framework dependency for hooks and component rendering.","package":"react","optional":false},{"reason":"Peer dependency often integrated for animations with styling libraries.","package":"react-native-reanimated","optional":true},{"reason":"Peer dependency likely for internal color normalization and compatibility.","package":"@react-native/normalize-colors","optional":false}],"imports":[{"note":"Used for global configuration (themes, breakpoints). Unistyles is primarily ESM-first, avoid CommonJS require().","wrong":"const UnistylesRegistry = require('react-native-unistyles').UnistylesRegistry","symbol":"UnistylesRegistry","correct":"import { UnistylesRegistry } from 'react-native-unistyles'"},{"note":"This is a named export, not a default export. Used to define type-safe stylesheets.","wrong":"import createStyleSheet from 'react-native-unistyles'","symbol":"createStyleSheet","correct":"import { createStyleSheet } from 'react-native-unistyles'"},{"note":"React Hook for consuming stylesheets within components. Automatically re-renders on theme or breakpoint changes.","wrong":"import { useStyles as useUnistyles } from 'react-native-unistyles'","symbol":"useStyles","correct":"import { useStyles } from 'react-native-unistyles'"},{"note":"Global singleton for runtime theme and breakpoint manipulation (e.g., `UnistylesRuntime.setTheme()`).","symbol":"UnistylesRuntime","correct":"import { UnistylesRuntime } from 'react-native-unistyles'"}],"quickstart":{"code":"import React from 'react';\nimport { View, Text, Pressable } from 'react-native';\nimport {\n  UnistylesRegistry,\n  createStyleSheet,\n  useStyles,\n  UnistylesRuntime\n} from 'react-native-unistyles';\n\n// 1. Define your themes\nconst lightTheme = {\n  colors: {\n    background: '#FFFFFF',\n    text: '#000000',\n    primary: '#6200EE'\n  }\n} as const; // 'as const' helps with type inference\n\nconst darkTheme = {\n  colors: {\n    background: '#121212',\n    text: '#FFFFFF',\n    primary: '#BB86FC'\n  }\n} as const;\n\n// 2. Define your breakpoints (optional, but powerful)\nconst breakpoints = {\n  sm: 0,\n  md: 768,\n  lg: 1024\n} as const;\n\n// 3. Register themes and breakpoints - crucial for TypeScript type inference\ntype AppBreakpoints = typeof breakpoints;\ntype AppThemes = {\n  light: typeof lightTheme;\n  dark: typeof darkTheme;\n};\n\ndeclare module 'react-native-unistyles' {\n  export interface UnistylesBreakpoints extends AppBreakpoints {}\n  export interface UnistylesThemes extends AppThemes {}\n}\n\nUnistylesRegistry.addBreakpoints(breakpoints)\n  .addThemes({\n    light: lightTheme,\n    dark: darkTheme\n  })\n  .setInitialTheme('light'); // Set initial theme\n\n// 4. Create your stylesheet\nconst stylesheet = createStyleSheet((theme) => ({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    backgroundColor: theme.colors.background\n  },\n  text: {\n    color: theme.colors.text,\n    fontSize: 20,\n    marginBottom: 20,\n    // Responsive styling using breakpoints\n    $$container: {\n      lg: { fontSize: 30 },\n      md: { fontSize: 24 }\n    }\n  },\n  button: {\n    backgroundColor: theme.colors.primary,\n    paddingVertical: 12,\n    paddingHorizontal: 24,\n    borderRadius: 8\n  },\n  buttonText: {\n    color: theme.colors.text === '#000000' ? '#FFFFFF' : '#000000', // Ensure contrast\n    fontSize: 16,\n    fontWeight: 'bold'\n  }\n}));\n\n// 5. Use the stylesheet in your component\nexport default function App() {\n  const { styles, theme } = useStyles(stylesheet);\n\n  const toggleTheme = () => {\n    UnistylesRuntime.setTheme(theme.name === 'light' ? 'dark' : 'light');\n  };\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.text}>\n        Current Theme: {theme.name}\n      </Text>\n      <Pressable onPress={toggleTheme} style={styles.button}>\n        <Text style={styles.buttonText}>Toggle Theme</Text>\n      </Pressable>\n    </View>\n  );\n}","lang":"typescript","description":"This quickstart demonstrates how to set up Unistyles by defining multiple themes and responsive breakpoints. It shows how to register them with `UnistylesRegistry`, create a stylesheet using `createStyleSheet`, apply styles to components using `useStyles`, and dynamically toggle between themes at runtime using `UnistylesRuntime`. This setup provides type-safe, performant, and responsive styling for React Native applications."},"warnings":[{"fix":"Refer to the official 'Migration from Unistyles 2.0' guide at https://unistyl.es/v3/start/migration-guide for detailed steps.","message":"Upgrading from Unistyles v2.0 to v3.0 involves significant breaking changes and requires following the official migration guide.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Check the Unistyles README for the compatibility table. For Unistyles >=3.2.0, you need `react-native-nitro-modules` >=0.35.2. Install with `yarn add react-native-nitro-modules@<version>`.","message":"`react-native-unistyles` v3.x has strict peer dependency requirements for `react-native-nitro-modules`. Ensure you install the compatible version.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js environment to 20.18.0 or newer and your React Native project to 0.76.0 or newer.","message":"Unistyles v3 requires Node.js version >= 20.18.0 and React Native version >= 0.76.0.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consider installing `react-native-edge-to-edge` or ensure `edgeToEdgeEnabled=true` is set in your Android project configuration. Expo SDK 54+ enables this automatically.","message":"The `react-native-edge-to-edge` dependency became optional from v3.1.0, but it's strongly recommended to enable `edgeToEdgeEnabled=true` in `android/gradle.properties` for proper system bar handling.","severity":"gotcha","affected_versions":">=3.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For iOS, navigate to your `ios/` directory and run `pod install`. For Android, ensure `react-native-unistyles` is correctly linked (often automatic with autolinking, but sometimes requires manual intervention or a clean build).","cause":"The native module for Unistyles was not correctly linked or built into your project, often due to missing 'pod install' on iOS or incorrect native setup on Android/other platforms.","error":"Native module 'Unistyles' was not found. Did you forget to run 'pod install'?"},{"fix":"Ensure `UnistylesRegistry.addThemes()`, `UnistylesRegistry.addBreakpoints()`, and `UnistylesRegistry.setInitialTheme()` are called once at the root of your application, typically in your `App.tsx` or a dedicated setup file.","cause":"The Unistyles global registry (for themes, breakpoints) was not configured before components attempted to use Unistyles hooks or functions.","error":"Uncaught Error: Unistyles registry is not initialized. Please ensure UnistylesRegistry.addThemes() and UnistylesRegistry.addBreakpoints() are called before using Unistyles."},{"fix":"Verify that `UnistylesRegistry.addThemes()` and `UnistylesRegistry.setInitialTheme()` have been properly invoked with valid theme objects.","cause":"This typically means the `theme` object passed to your stylesheet function or accessed directly from `useStyles` is undefined or malformed, likely because the themes were not correctly registered with `UnistylesRegistry` or the initial theme was not set.","error":"TypeError: Cannot read properties of undefined (reading 'colors')"},{"fix":"Update all `require()` statements for `react-native-unistyles` to ES Module `import` statements (e.g., `import { useStyles } from 'react-native-unistyles';`).","cause":"Attempting to use CommonJS `require()` syntax to import `react-native-unistyles` in an environment that expects ES Modules, or when your project configuration is set for ESM.","error":"SyntaxError: require() not supported"}],"ecosystem":"npm"}