React Native Unistyles

Common errors

• Native module 'Unistyles' was not found. Did you forget to run 'pod install'?

  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.
  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).

• Uncaught Error: Unistyles registry is not initialized. Please ensure UnistylesRegistry.addThemes() and UnistylesRegistry.addBreakpoints() are called before using Unistyles.

  cause The Unistyles global registry (for themes, breakpoints) was not configured before components attempted to use Unistyles hooks or functions.
  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.

• TypeError: Cannot read properties of undefined (reading 'colors')

  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.
  fix Verify that `UnistylesRegistry.addThemes()` and `UnistylesRegistry.setInitialTheme()` have been properly invoked with valid theme objects.

• SyntaxError: require() not supported

  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.
  fix Update all `require()` statements for `react-native-unistyles` to ES Module `import` statements (e.g., `import { useStyles } from 'react-native-unistyles';`).

Warnings

• breaking Upgrading from Unistyles v2.0 to v3.0 involves significant breaking changes and requires following the official migration guide.
  Fix: Refer to the official 'Migration from Unistyles 2.0' guide at https://unistyl.es/v3/start/migration-guide for detailed steps.
• breaking `react-native-unistyles` v3.x has strict peer dependency requirements for `react-native-nitro-modules`. Ensure you install the compatible version.
  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>`.
• breaking Unistyles v3 requires Node.js version >= 20.18.0 and React Native version >= 0.76.0.
  Fix: Upgrade your Node.js environment to 20.18.0 or newer and your React Native project to 0.76.0 or newer.
• gotcha 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.
  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.

Install

• npm install react-native-unistyles npm
• yarn add react-native-unistyles yarn
• pnpm add react-native-unistyles pnpm

Imports

• UnistylesRegistry
  wrong:

  const UnistylesRegistry = require('react-native-unistyles').UnistylesRegistry

  correct:

  import { UnistylesRegistry } from 'react-native-unistyles'

  Used for global configuration (themes, breakpoints). Unistyles is primarily ESM-first, avoid CommonJS require().
• createStyleSheet
  wrong:

  import createStyleSheet from 'react-native-unistyles'

  correct:

  import { createStyleSheet } from 'react-native-unistyles'

  This is a named export, not a default export. Used to define type-safe stylesheets.
• useStyles
  wrong:

  import { useStyles as useUnistyles } from 'react-native-unistyles'

  correct:

  import { useStyles } 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()`).

Quickstart

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>
  );
}