react-native-unistyles

Unistyles is a cross-platform styling library for React Native that allows you to share up to 100% of your styles across all platforms. It acts as a superset of the standard React Native StyleSheet, providing enhanced capabilities while maintaining a familiar API.

Key features include:

• Performance: Uses pure JSI bindings and C++ to guarantee no re-renders across the app without relying on hooks or context.
• Compatibility: Does not pollute the native view hierarchy, allowing it to be used with any component.
• Consistency: Includes a cross-platform parser written in C++ for consistent output.
• Type Safety: Leverages Nitro Modules for strongly typed operations.
• Enhanced Stylesheets: Transforms standard StyleSheets into enhanced versions that can access themes and platform-specific values.

Unlike traditional styling libraries that require a full React re-render to reflect style changes, Unistyles 3.0 uses a C++ engine to perform atomic updates.

When a relevant event occurs (such as a theme change, orientation change, or accessibility setting update), Unistyles:

1. Scans the StyleSheetRegistry to find affected styles.
2. Uses the ShadowRegistry to identify which ShadowNode is bound to those styles.
3. Translates updates into atomic ShadowTree instructions.
4. Updates the ShadowTree directly from C++, meaning your React components do not need to re-render to reflect the new styles.

In Unistyles 3.0, the web implementation is independent of React Native Web. It uses a custom web parser that converts StyleSheet definitions directly into CSS.

Key behaviors:

• Class Generation: The parser generates unique classNames for styles and assigns them to DOM elements.
• Media Queries: Media queries are automatically generated based on your defined breakpoints, which optimizes performance by avoiding recalculations on every resize.
• CSS Output: Shared properties (like flex: 1) are consolidated into single classes, while responsive properties (like fontSize with breakpoints) are wrapped in @media queries.

Unistyles v3 enforces edge-to-edge layout on Android. Instead of using react-native-safe-area-context, use rt.insets within your StyleSheet.create callback to handle status bar and navigation bar insets accurately.

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    flex: 1,
    paddingTop: rt.insets.top,
    paddingBottom: rt.insets.bottom
  }
}))

To enable autocomplete for theme properties and breakpoint keys, declare the UnistylesThemes and UnistylesBreakpoints interfaces within the react-native-unistyles module in a declaration file (e.g., unistyles.d.ts).

// unistyles.d.ts (or in your config file)
import { lightTheme, darkTheme } from './themes'
import { breakpoints } from './breakpoints'

type AppThemes = {
  light: typeof lightTheme
  dark: typeof darkTheme
}

declare module 'react-native-unistyles' {
  export interface UnistylesThemes extends AppThemes {}
  export interface UnistylesBreakpoints extends typeof breakpoints {}
}

To use Unistyles for styling, replace the standard react-native StyleSheet import with react-native-unistyles.

When using Unistyles, StyleSheet.create accepts a callback function that receives the theme object. This function is automatically re-invoked whenever the theme changes, ensuring styles stay synchronized with the current theme state.

import { StyleSheet } from 'react-native-unistyles';

const styles = StyleSheet.create(theme => ({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
}));

To ensure themes and breakpoints are available before any application code runs, you must configure Unistyles at the very start of your app's lifecycle.

1. Update package.json to change the main entry point from expo-router/entry to index.ts.
2. Create an index.ts file in your project root that imports the standard Expo Router entry and your Unistyles configuration file.

// package.json
{
  "main": "index.ts"
}

// index.ts
import 'expo-router/entry'
import './unistyles'

Breakpoints are key/value pairs that define screen size boundaries. To register them, create a constant object where the first breakpoint must start with 0 to enable CSS-like cascading behavior.

If using TypeScript, you must extend the UnistylesBreakpoints interface to ensure type safety for your custom keys.

// 1. Define breakpoints
const breakpoints = {
    xs: 0,
    sm: 576,
    md: 768,
    lg: 992,
    xl: 1200,
    superLarge: 2000,
    tvLike: 4000
} as const

// 2. TypeScript augmentation
type AppBreakpoints = typeof breakpoints

declare module 'react-native-unistyles' {
  export interface UnistylesBreakpoints extends AppBreakpoints {}
}

// 3. Register via StyleSheet.configure
import { StyleSheet } from 'react-native-unistyles'

StyleSheet.configure({
    breakpoints
})

If you are using an LLM (Large Language Model) to assist with Unistyles 3.0 development, you can provide it with auto-generated documentation files to improve its context and accuracy. Unistyles provides three versions of documentation optimized for different LLM consumption needs:

• llms.txt: Standard documentation format.
• short documentation: A condensed version for smaller context windows.
• full documentation: A comprehensive version for deep context.

You can point your LLM or AI coding agent to these URLs to feed it the relevant Unistyles 3.0 knowledge.

Before migrating to Unistyles v3, ensure your environment meets these mandatory requirements:

• React Native: 0.78.0+ with New Architecture enabled.
• React: 19+
• Native Dependencies: react-native-nitro-modules and react-native-edge-to-edge (for Android edge-to-edge insets).
• Expo: SDK 53+ (requires Dev Client or Prebuild; not compatible with Expo Go).
• iOS: Xcode 16+.