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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UnistylesRegistry
✓ import { UnistylesRegistry } from 'react-native-unistyles'
✗ const UnistylesRegistry = require('react-native-unistyles').UnistylesRegistry
Used for global configuration (themes, breakpoints). Unistyles is primarily ESM-first, avoid CommonJS require().
createStyleSheet
✓ import { createStyleSheet } from 'react-native-unistyles'
✗ import createStyleSheet from 'react-native-unistyles'
This is a named export, not a default export. Used to define type-safe stylesheets.
useStyles
✓ import { useStyles } from 'react-native-unistyles'
✗ import { useStyles as useUnistyles } from 'react-native-unistyles'
React Hook for consuming stylesheets within components. Automatically re-renders on theme or breakpoint changes.
UnistylesRuntime
✓ import { UnistylesRuntime } from 'react-native-unistyles'
Global singleton for runtime theme and breakpoint manipulation (e.g., `UnistylesRuntime.setTheme()`).
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.
import React from 'react';
import { View, Text, Pressable } from 'react-native';
import {
UnistylesRegistry,
createStyleSheet,
useStyles,
UnistylesRuntime
} from 'react-native-unistyles';
// 1. Define your themes
const lightTheme = {
colors: {
background: '#FFFFFF',
text: '#000000',
primary: '#6200EE'
}
} as const; // 'as const' helps with type inference
const darkTheme = {
colors: {
background: '#121212',
text: '#FFFFFF',
primary: '#BB86FC'
}
} as const;
// 2. Define your breakpoints (optional, but powerful)
const breakpoints = {
sm: 0,
md: 768,
lg: 1024
} as const;
// 3. Register themes and breakpoints - crucial for TypeScript type inference
type AppBreakpoints = typeof breakpoints;
type AppThemes = {
light: typeof lightTheme;
dark: typeof darkTheme;
};
declare module 'react-native-unistyles' {
export interface UnistylesBreakpoints extends AppBreakpoints {}
export interface UnistylesThemes extends AppThemes {}
}
UnistylesRegistry.addBreakpoints(breakpoints)
.addThemes({
light: lightTheme,
dark: darkTheme
})
.setInitialTheme('light'); // Set initial theme
// 4. Create your stylesheet
const stylesheet = createStyleSheet((theme) => ({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: theme.colors.background
},
text: {
color: theme.colors.text,
fontSize: 20,
marginBottom: 20,
// Responsive styling using breakpoints
$$container: {
lg: { fontSize: 30 },
md: { fontSize: 24 }
}
},
button: {
backgroundColor: theme.colors.primary,
paddingVertical: 12,
paddingHorizontal: 24,
borderRadius: 8
},
buttonText: {
color: theme.colors.text === '#000000' ? '#FFFFFF' : '#000000', // Ensure contrast
fontSize: 16,
fontWeight: 'bold'
}
}));
// 5. Use the stylesheet in your component
export default function App() {
const { styles, theme } = useStyles(stylesheet);
const toggleTheme = () => {
UnistylesRuntime.setTheme(theme.name === 'light' ? 'dark' : 'light');
};
return (
<View style={styles.container}>
<Text style={styles.text}>
Current Theme: {theme.name}
</Text>
<Pressable onPress={toggleTheme} style={styles.button}>
<Text style={styles.buttonText}>Toggle Theme</Text>
</Pressable>
</View>
);
}
Errors
Common errors & fixes
Native module 'Unistyles' was not found. Did you forget to run 'pod install'?
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.
fixFor 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).
Uncaught Error: Unistyles registry is not initialized. Please ensure UnistylesRegistry.addThemes() and UnistylesRegistry.addBreakpoints() are called before using Unistyles.
The Unistyles global registry (for themes, breakpoints) was not configured before components attempted to use Unistyles hooks or functions.
fixEnsure `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.
TypeError: Cannot read properties of undefined (reading 'colors')
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.
fixVerify that `UnistylesRegistry.addThemes()` and `UnistylesRegistry.setInitialTheme()` have been properly invoked with valid theme objects.
SyntaxError: require() not supported
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.
fixUpdate all `require()` statements for `react-native-unistyles` to ES Module `import` statements (e.g., `import { useStyles } from 'react-native-unistyles';`). Audit
Dependencies
react-native-nitro-modulesrequiredCore native module for performance and JSI bindings. Strict version compatibility is required (e.g., Unistyles >=3.2.0 requires Nitro Modules >=0.35.2).
react-native-edge-to-edgeoptionalRecommended for comprehensive edge-to-edge support and system bar management, but optional since v3.1.0. Automatically enabled by Expo SDK 54+.
react-nativerequiredCore React Native framework, required minimum v0.76.0 for Unistyles v3.
reactrequiredReact framework dependency for hooks and component rendering.
react-native-reanimatedoptionalPeer dependency often integrated for animations with styling libraries.
@react-native/normalize-colorsrequiredPeer dependency likely for internal color normalization and compatibility.