Migrate react-native-unistyles from v2 to v3. Triggers on: "migrate unistyles", "upgrade unistyles", "v2 to v3", "unistyles migration", "update unistyles", "convert unistyles v2". Covers all API changes including StyleSheet.create, useStyles removal, theme configuration, variants, withUnistyles, Babel plugin setup, style spreading fixes, and third-party component wrapping.
You are migrating a React Native codebase from react-native-unistyles v2 to v3. Follow this workflow precisely. v3 is a complete rewrite with C++ core (Nitro Modules), no re-renders, and a Babel plugin that processes StyleSheets at build time.
react-native-nitro-modules (native bridge dependency)react-native-edge-to-edge (required for Android edge-to-edge insets)Follow these steps IN ORDER. Each step must be completed before moving to the next.
Install react-native-unistyles@3 and add the Babel plugin:
// babel.config.js
module.exports = {
plugins: [
['react-native-unistyles/plugin', { root: 'src' }] // your app source root
]
}
The root option is REQUIRED. It tells the plugin which directory contains your app code. Files outside this directory (except node_modules paths you explicitly configure) won't be processed.
If using React Compiler, the Unistyles plugin MUST come BEFORE React Compiler in the plugins array.
- import { UnistylesRegistry } from 'react-native-unistyles'
+ import { StyleSheet } from 'react-native-unistyles'
- UnistylesRegistry
- .addThemes({ light: lightTheme, dark: darkTheme })
- .addBreakpoints({ sm: 0, md: 768, lg: 1200 })
- .addConfig({
- adaptiveThemes: true,
- initialTheme: 'dark',
- plugins: [myPlugin],
- experimentalCSSMediaQueries: true,
- windowResizeDebounceTimeMs: 100,
- disableAnimatedInsets: true
- })
+ StyleSheet.configure({
+ themes: { light: lightTheme, dark: darkTheme },
+ breakpoints: { sm: 0, md: 768, lg: 1200 },
+ settings: {
+ adaptiveThemes: true,
+ initialTheme: 'dark'
+ }
+ })
Removed settings: plugins, experimentalCSSMediaQueries (now always on), windowResizeDebounceTimeMs (no debounce), disableAnimatedInsets (insets no longer re-render).
Unistyles StyleSheet is a full polyfill of React Native's StyleSheet — it includes hairlineWidth, compose, flatten, absoluteFill, and absoluteFillObject. You should replace all import { StyleSheet } from 'react-native' with import { StyleSheet } from 'react-native-unistyles' so you have a single import.
- import { StyleSheet } from 'react-native'
- import { createStyleSheet } from 'react-native-unistyles'
+ import { StyleSheet } from 'react-native-unistyles'
- const stylesheet = createStyleSheet(theme => ({
+ const styles = StyleSheet.create(theme => ({
container: {
backgroundColor: theme.colors.background
}
}))
- import { useStyles } from 'react-native-unistyles'
const MyComponent = () => {
- const { styles, theme } = useStyles(stylesheet)
return <View style={styles.container} />
}
Styles created with StyleSheet.create are used directly - no hook needed. The Babel plugin handles reactivity at build time.
- import { useInitialTheme } from 'react-native-unistyles'
-
- const App = () => {
- useInitialTheme(storage.getString('preferredTheme') ?? 'light')
- return <Stack />
- }
+ // In your configure call:
+ StyleSheet.configure({
+ settings: {
+ initialTheme: () => storage.getString('preferredTheme') ?? 'light'
+ }
+ })
initialTheme accepts a string or a synchronous function.
For components that used useStyles() (without a stylesheet) just to get theme/runtime:
Option A - withUnistyles (preferred for passing theme-derived props):
import { withUnistyles } from 'react-native-unistyles'
const UniButton = withUnistyles(Button, (theme, rt) => ({
color: theme.colors.primary,
size: rt.screen.width > 400 ? 'large' : 'small'
}))
// Usage: <UniButton />
Option B - useUnistyles hook (quick migration path):
import { useUnistyles } from 'react-native-unistyles'
const MyComponent = () => {
const { theme, rt } = useUnistyles()
return <Text style={{ color: theme.colors.primary }}>{rt.screen.width}</Text>
}
WARNING: useUnistyles causes re-renders when theme/runtime changes. Prefer withUnistyles or StyleSheet.create(theme => ...) for performance.
- const { styles } = useStyles(stylesheet, { size: 'large', color: 'primary' })
+ styles.useVariants({ size: 'large', color: 'primary' })
Call styles.useVariants() at the top of your component (like a hook). It must be called before accessing styles that use variants.
v3 styles are C++ proxy objects. Spreading breaks the binding.
- <View style={{ ...styles.container, ...styles.extra }} />
+ <View style={[styles.container, styles.extra]} />
- <View style={{ ...styles.container, marginTop: 10 }} />
+ <View style={[styles.container, { marginTop: 10 }]} />
NEVER use {...styles.x}. ALWAYS use [styles.x, styles.y] array syntax.
The plugin system is removed. Replace plugins with static functions in your theme or StyleSheet:
- // Plugin approach (v2)
- const fontPlugin: UnistylesPlugin = {
- name: 'fontPlugin',
- onParsedStyle: (_key, styles) => {
- if ('fontWeight' in styles) {
- styles.fontFamily = styles.fontWeight === 'bold' ? 'Roboto-Bold' : 'Roboto-Regular'
- }
- return styles
- }
- }
+ // v3: Use a helper function in your theme or directly
+ const styles = StyleSheet.create(theme => ({
+ text: {
+ fontFamily: theme.utils.getFontFamily('bold')
+ }
+ }))
UnistylesProvider no longer exists. Simply remove it from your component tree.
Renamed/changed methods:
UnistylesRuntime.setImmersiveMode(bool) replaces separate status bar/nav bar hideUnistylesRuntime.setRootViewBackgroundColor(color) - no more alpha parameterStyleSheet.hairlineWidth instead of UnistylesRuntime.hairlineWidthRemoved methods:
addPlugin(plugin), removePlugin(plugin), enabledPluginsstatusBar.setColor(color), navigationBar.setColor(color)New properties on UnistylesRuntime:
statusBar object with setHidden(hidden, animation) and setStyle(style)navigationBar object with setHidden(hidden)insets.ime for keyboard inset- type AppThemes = { light: typeof lightTheme, dark: typeof darkTheme }
+ type AppThemes = typeof themes // where themes = { light: lightTheme, dark: darkTheme }
declare module 'react-native-unistyles' {
export interface UnistylesThemes extends AppThemes {}
+ export interface UnistylesBreakpoints extends typeof breakpoints {}
}
- import { useAnimatedKeyboard } from 'react-native-reanimated'
- const keyboard = useAnimatedKeyboard()
+ // Use ime inset in StyleSheet
+ const styles = StyleSheet.create((theme, rt) => ({
+ container: {
+ paddingBottom: rt.insets.ime
+ }
+ }))
// jest.setup.js
require('react-native-unistyles/mocks')
require('./unistyles.config') // your StyleSheet.configure call
The Babel plugin auto-disables in test environments (NODE_ENV=test).
If the project uses Expo Router, extra steps are needed because Expo Router resolves routes before Unistyles can initialize.
1. Change the main entry point in package.json:
{ "main": "index.ts" }
2. Create index.ts that imports Unistyles config before the router:
import 'expo-router/entry'
import './unistyles' // your StyleSheet.configure() file
3. For static rendering (Expo SDK 52+): import the Unistyles config in +html.tsx as well:
import '../unistyles' // ensures Unistyles initializes for each static page
import { ScrollViewStyleReset } from 'expo-router/html';
import { type PropsWithChildren } from 'react';
// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta httpEquiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
{/*
Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
*/}
<ScrollViewStyleReset />
{/* Add any additional <head> elements that you want globally available on web... */}
</head>
<body>{children}</body>
</html>
);
}
See https://www.unistyl.es/v3/guides/expo-router for full details.
| v2 | v3 |
|---|---|
createStyleSheet | StyleSheet.create |
useStyles(stylesheet) | Use styles directly (no hook) |
useStyles() for theme | useUnistyles() or withUnistyles |
useStyles(ss, variants) | styles.useVariants(variants) |
useInitialTheme(name) | settings.initialTheme in configure |
UnistylesRegistry.addThemes() | StyleSheet.configure({ themes }) |
UnistylesRegistry.addBreakpoints() | StyleSheet.configure({ breakpoints }) |
UnistylesRegistry.addConfig() | StyleSheet.configure({ settings }) |
UnistylesProvider | Removed (not needed) |
UnistylesPlugin | Removed (use theme functions) |
{...styles.x, ...styles.y} | [styles.x, styles.y] |
UnistylesRuntime.hairlineWidth | StyleSheet.hairlineWidth |
statusBar.setColor() | Removed |
navigationBar.setColor() | Removed |
import { StyleSheet } from 'react-native' | import { StyleSheet } from 'react-native-unistyles' (full polyfill) |
When a third-party component needs theme values or Unistyles styles:
style prop? -> Pass Unistyles styles directly (Babel plugin handles it for standard RN components)color)? -> Wrap with withUnistylesautoProcessPaths in Babel pluginuseUnistyles() hook as fallback[styles.a, styles.b]StyleSheet from react-native-unistyles only - it polyfills all RN StyleSheet APIs (hairlineWidth, compose, flatten, absoluteFill, etc.), so remove any import { StyleSheet } from 'react-native'StyleSheet from barrel files - the Babel plugin won't detect itstyles.useVariants() must be called before accessing styles in the component render