Setup

1. Install package

yarn add react-native-unistyles

2. Finish installation

Expo

Dev client only

Unistyles includes custom native code, which means it does not support Expo Go.

To finish the setup use expo dev client and run prebuild command:

yarn expo prebuild --clean

Bare

Library supports autolinking, to finish the setup run pod install:

cd ios && pod install

Web

Unistyles offers first-class support for React Native Web. To run the project, we recommend following the guidelines provided by Expo:

yarn expo add react-dom react-native-web @expo/metro-runtime

NextJS

Library supports also Server Side Rendering. We recommend to setup to project with Solito:

npx create-solito-app@latest my-solito-app

macOS

You can also style your macOS apps using react-native-unistyles. Please follow the instructions provided by react-native-macos and then:

Open macos/Podfile and add the following line:

Podfile

target 'macos-macOS' do
  # add this line somewhere within the target scope
  pod 'react-native-unistyles', :path => '../node_modules/react-native-unistyles'
end

Then run pod install:

macos

pod install

Caution

Remember to add this line to the macos folder, not the ios folder!

Windows

2.3.0

Windows is also supported with react-native-windows package. Simply install the package and it will be auto-linked.

tvOS

Please follow official installation guide for react-native-tvOS:

Then run pod install:

tvos

pod install

visionOS

Please follow the instructions provided by react-native-visionos:

Then run pod install:

visionos

pod install

3. Configure Unistyles with UnistylesRegistry

Every step mentioned here is optional. If you don’t want to use theming, breakpoints, or any other setting, you don’t need to even call UnistylesRegistry. You can jump directly into working on your components.

Remember that UnistylesRegistry should be called only once. If you want to interact with Unistyles use UnistylesRuntime as described here.

3.1 Define your breakpoints

You can name your breakpoints however you like. The only restriction is that the first breakpoint must start with 0:

breakpoints.ts

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

3.2 Define your theme(s)

You can define as many themes as you want. Each theme just needs to have a unique name and the same type. The library has no restrictions on the shape of the theme. You can use nested objects, functions, spread operators, and so on.

themes.ts

 export const lightTheme = {
   colors: {
     typography: '#000000',
     background: '#ffffff'
   },
   margins: {
     sm: 2,
     md: 4,
     lg: 8,
     xl: 12
   }
 } as const

 export const darkTheme = {
   colors: {
     typography: '#ffffff',
     background: '#000000'
   },
   margins: {
     sm: 2,
     md: 4,
     lg: 8,
     xl: 12
   }
 } as const

 // define other themes

3.3 Configure TypeScript

If you’re using TypeScript, create types for your breakpoints and/or themes. This step is required to achieve perfect Intellisense support across all StyleSheets.

unistyles.ts

// if you defined breakpoints
type AppBreakpoints = typeof breakpoints

// if you defined themes
type AppThemes = {
  light: typeof lightTheme,
  dark: typeof darkTheme
}

// override library types
declare module 'react-native-unistyles' {
  export interface UnistylesBreakpoints extends AppBreakpoints {}
  export interface UnistylesThemes extends AppThemes {}
}

Did you encounter errors like these?

"An interface declaring no members is equivalent to its supertype."

Don’t worry! This issue arises due to the eslint preset. To fix it, disable the following rule.

"TS2664: Invalid module name in augmentation, module 'react-native-unistyles' cannot be found."

To resolve this, simply follow the steps described below. You need to import something from react-native-unistyles.

3.4 Call UnistylesRegistry

The final step is to call UnistylesRegistry to pass your themes, breakpoints and optional config.

unistyles.ts

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

UnistylesRegistry
  .addBreakpoints(breakpoints)
  .addThemes({
    light: lightTheme,
    dark: darkTheme,
    // register other themes with unique names
  })
  .addConfig({
    // you can pass here optional config described below
    adaptiveThemes: true
  })

Caution

In order to run the code don’t forget to import the unistyles.ts file somewhere in your app eg. in the App.tsx file.

import '../unistyles'

Optional config

UnistylesRegistry has a method called addConfig that let’s you use some cool additional features. List of all available settings can be found here.

3.5 Full example

unistyles.ts

import { UnistylesRegistry } from 'react-native-unistyles'
import { breakpoints } from './breakpoints'
import { lightTheme, darkTheme } from './themes'

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,
  })
  .addConfig({
    adaptiveThemes: true
  })