/react-native-unistyles-v3

name: react-native-unistyles-v3
description: >
  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",
  "withUnistylesConfig", "unistyles metro". Covers setup (Babel plugin or Metro integration), theming, responsive design, variants, web features, third-party integration,
  and troubleshooting.
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Glob, Edit, Write, Bash(npx *)

React Native Unistyles v3 Skill

You are assisting with React Native Unistyles v3 styling. v3 is a zero-re-render styling library with a C++ core (Nitro Modules) and a Babel plugin that processes StyleSheets at build time (since 3.6.0, Metro apps can use the experimental zero-config Metro integration instead, which needs no Babel transform). It replaces React Native's `StyleSheet` with a reactive, theme-aware, responsive system.

Prerequisites

• React Native 0.85+ with **New Architecture mandatory** (the only architecture since RN 0.82)
• React 19+ (enforced at runtime)
• `react-native-nitro-modules` (native bridge dependency; pin an exact version — Unistyles 3.4.0+ needs `>= 0.37.1`)
• iOS 15.1+, Android 7+
• `react-native-edge-to-edge` is not needed (optional since v3.1.0, now deprecated) — set `edgeToEdgeEnabled=true` in `android/gradle.properties` instead (Expo SDK 54+ enables it automatically)
• Expo SDK 56+ (if using Expo; **not compatible with Expo Go** — requires dev client or prebuild)
• Xcode 16.4+ (iOS, required by Nitro Modules)

Workflow

1. **Read user's code first** — understand current setup, imports, and styling approach 2. **Identify intent** — new setup, add theming, responsive design, fix an issue, etc. 3. **Apply v3 patterns** — use the correct API from this skill; consult reference files for details 4. **Verify correctness** — check for critical rule violations (spreading, barrel re-exports, etc.)

Quick Reference

StyleSheet.create — 3 overloads

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 — one-time setup

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,            // web: themes as CSS variables (default: true)
    // nativeBreakpointsMode: 'pixels' | 'points'  // default 'pixels' = compare against rt.screen (pt/dp)
  }
})

Variants

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 (always pass an object, `{}` for defaults)
const variantStyles = styles.useVariants({ size: 'large', color: 'primary' })
return <View style={variantStyles.button} />

withUnistyles — map theme/runtime to non-style props, or wrap views Unistyles can't bind to

React Native / Reanimated views that only take `style` need no wrapping. Use `withUnistyles` for props like `color`/`trackColor`, for `contentContainerStyle`, or for third-party views that don't expose a native ref.

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" />
// Per-instance mapping: <UniButton uniProps={theme => ({ color: isOn ? theme.colors.on : theme.colors.off })} />

Critical Rules

1. **NEVER spread styles** — `{...styles.x}` breaks C++ proxy binding. ALWAYS use array syntax: `[styles.x, styles.y]` or `[styles.x, { marginTop: 10 }]` 2. **NEVER re-export StyleSheet from barrel files** — import it directly from `react-native-unistyles`. Outside `root`, the Babel plugin only recognizes `StyleSheet.create` via that import (or `autoProcessImports`), so a re-export silently breaks detection. (The Metro integration has no such limitation, but direct imports work everywhere.) 3. **A build-time integration is REQUIRED** — one of:

• Babel plugin (default): `['react-native-unistyles/plugin', { root: 'src' }]` in babel.config.js (`root` is required; every file under it is processed)
• Metro integration (3.6.0+, experimental, Metro only): `withUnistylesConfig(config)` from `react-native-unistyles/metro` in metro.config.js, no options, and remove the Babel plugin (having both throws). Dependencies are tracked at runtime, and `useVariants` must use the returned styles: `const variantStyles = styles.useVariants({ size }