Guide for using react-native-unistyles v3. Triggers on: "unistyles", "StyleSheet.create", "create stylesheet", "add theme", "breakpoints", "variants", "withUnistyles", "useUnistyles", "ScopedTheme", "UnistylesRuntime", "style component", "responsive styles", "media queries", "dynamic styles", "scoped theme", "adaptive theme", "unistyles setup", "unistyles config". Covers setup, theming, responsive design, variants, web features, third-party integration, and troubleshooting.
You are assisting with React Native Unistyles v3 styling. v3 is a zero-re-render styling library with a C++ core (Nitro Modules) and Babel plugin that processes StyleSheets at build time. It replaces React Native's StyleSheet with a reactive, theme-aware, responsive system.
react-native-nitro-modules (native bridge dependency)react-native-edge-to-edge (required for Android edge-to-edge insets)import { StyleSheet } from 'react-native-unistyles'
// 1. Static object compatible with React Native StyleSheet.create
const styles = StyleSheet.create({
container: { flex: 1, padding: 16 }
})
// 2. Theme function (reactive to theme changes, zero re-renders)
const styles = StyleSheet.create(theme => ({
container: { backgroundColor: theme.colors.background }
}))
// 3. Theme + miniRuntime function (reactive to theme AND device state)
const styles = StyleSheet.create((theme, rt) => ({
container: {
backgroundColor: theme.colors.background,
paddingTop: rt.insets.top,
width: rt.screen.width > 768 ? 500 : rt.screen.width - 32
}
}))
StyleSheet.configure({
themes: { light: lightTheme, dark: darkTheme },
breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
settings: {
initialTheme: 'light', // or: () => storage.getString('theme') ?? 'light'
// adaptiveThemes: true, // auto-switch light/dark based on OS (mutually exclusive with initialTheme)
// CSSVars: true, // use CSS custom properties on web
// nativeBreakpointsMode: 'pixels' | 'points'
}
})
const styles = StyleSheet.create(theme => ({
button: {
variants: {
size: {
small: { padding: 4 },
medium: { padding: 8 },
large: { padding: 16 },
},
color: {
primary: { backgroundColor: theme.colors.primary },
secondary: { backgroundColor: theme.colors.secondary },
}
},
compoundVariants: [
{ size: 'large', color: 'primary', styles: { borderWidth: 2 } }
],
}
}))
// In component — call useVariants BEFORE accessing styles
styles.useVariants({ size: 'large', color: 'primary' })
return <View style={styles.button} />
import { withUnistyles } from 'react-native-unistyles'
import { Button } from 'some-library'
const UniButton = withUnistyles(Button, (theme, rt) => ({
color: theme.colors.primary,
size: rt.screen.width > 400 ? 'large' : 'small'
}))
// Usage: <UniButton title="Press me" />
{...styles.x} breaks C++ proxy binding. ALWAYS use array syntax: [styles.x, styles.y] or [styles.x, { marginTop: 10 }]StyleSheet.create by import source. Re-exporting breaks detection.['react-native-unistyles/plugin', { root: 'src' }] to babel.config.js. Without it, styles won't be reactive.react-native-unistyles only — it polyfills all RN StyleSheet APIs (hairlineWidth, compose, flatten, absoluteFill). Replace all import { StyleSheet } from 'react-native'.styles.useVariants() must be called before accessing variant-dependent styles — treat it like a React hook (top of component).StyleSheet.create(theme => ...) over useUnistyles() — theme functions cause zero re-renders; useUnistyles() re-renders on every theme/runtime change.StyleSheet.configure() must be called before any StyleSheet.create() — typically in your app entry point, before any component renders.Need theme/runtime in styles?
├─ YES → StyleSheet.create((theme, rt) => ...) [zero re-renders]
└─ NO → StyleSheet.create({ ... }) [static styles]
Need theme values as non-style props?
├─ YES → withUnistyles(Component, (theme, rt) => ({ propName: theme.value }))
└─ NO → Pass Unistyles styles via style prop directly
Need theme/runtime in component logic (not just styles)?
├─ YES → useUnistyles() hook [causes re-renders]
└─ NO → Use StyleSheet.create with theme function
Does the component accept a `style` prop?
├─ YES → Pass Unistyles styles directly (Babel auto-processes standard RN views)
│ If it's a custom native view → add to autoProcessPaths in Babel config
├─ NO → Does it accept theme-derived props (color, size, etc.)?
│ ├─ YES → withUnistyles(Component, (theme, rt) => ({ prop: theme.value }))
│ └─ NO → useUnistyles() as fallback
└─ Component from node_modules not processed?
→ Add its path to autoProcessPaths or autoProcessImports in Babel plugin config