Configuration

To unlock more features and tailor Unistyles to your needs, you can configure it. The Unistyles configuration is divided into three parts:

1. Themes
2. Breakpoints
3. Settings

Note

Each configuration is optional but enables advanced features, which are explained in the guide How Unistyles Works?

Themes (Optional)

Themes is a JavaScript object where the keys represent unique theme names, and the values are the corresponding theme definitions. For more details, refer to the theming guide.

unistyles.ts

const lightTheme = {
    colors: {
        primary: '#ff1ff4',
        secondary: '#1ff4ff'
        // any nesting, spreading, arrays, etc.
    },
    // functions, external imports, etc.
    gap: (v: number) => v * 8
}

const otherTheme = {
    colors: {
        primary: '#aa12ff',
        secondary: 'pink'
    },
    gap: (v: number) => v * 8
}

const appThemes = {
    light: lightTheme,
    other: otherTheme
}

Note

Unistyles supports any dynamic theme and doesn’t enforce a specific structure. To avoid TypeScript issues, ensure that all themes share the same type.

Breakpoints (Optional)

Breakpoints is a JavaScript object where the keys are unique breakpoint names and the values are the corresponding breakpoint values (numbers). Be sure to register at least one breakpoint with a value of 0, as it’s required to simulate the cascading behavior of CSS media queries.

unistyles.ts

const breakpoints = {
    xs: 0, // <-- make sure to register one breakpoint with value 0
    sm: 300,
    md: 500,
    lg: 800,
    xl: 1200
    // use as many breakpoints as you need
}

Settings (Optional)

The Settings object has been simplified, and in the most recent version, it supports only four properties:

• adaptiveThemes – a boolean that enables or disables adaptive themes learn more
• initialTheme – a string or a synchronous function that sets the initial theme
• CSSVars – a boolean that enables or disables web CSS variables (defaults to true) learn more
• nativeBreakpointsMode - iOS/Android only. User preferred mode for breakpoints. Can be either points or pixels (defaults to pixels) learn more

unistyles.ts

const settings = {
    initialTheme: 'light'
}

// or with a synchronous function
const settings = {
    initialTheme: () => {
        // get preferred theme from user's preferences/MMKV/SQL/StanJS etc.

        return storage.getString('preferredTheme') ?? 'light'
    }
}

// or with adaptive themes
const settings = {
    adaptiveThemes: true
}

Note

In the Unistyles 3.0 setting both initialTheme and adaptiveThemes will cause an error. These options are mutually exclusive.

TypeScript Types (Optional)

If your repository is using TypeScript, it is highly recommended to override the library types for optimal autocomplete and type safety regarding your themes and breakpoints:

unistyles.ts

type AppThemes = typeof appThemes
type AppBreakpoints = typeof breakpoints

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

Set configuration

The final step in the configuration is to set all the options by calling the StyleSheet.configure function:

unistyles.ts

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

StyleSheet.configure({
    themes: appThemes,
    breakpoints,
    settings
})

That’s it! You can now use all the features of Unistyles in your project!

Note

Don’t forget to import this config somewhere in your project, for example in index.ts file. You must call StyleSheet.configure before any StyleSheet.create call.

For expo router users, please refer to the Expo Router guide.

Full example

unistyles.ts

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

const lightTheme = {
    colors: {
        primary: '#ff1ff4',
        secondary: '#1ff4ff'
    },
    gap: (v: number) => v * 8
}

const otherTheme = {
    colors: {
        primary: '#aa12ff',
        secondary: 'pink'
    },
    gap: (v: number) => v * 8
}

const appThemes = {
    light: lightTheme,
    other: otherTheme
}

const breakpoints = {
    xs: 0,
    sm: 300,
    md: 500,
    lg: 800,
    xl: 1200
}

type AppBreakpoints = typeof breakpoints
type AppThemes = typeof appThemes

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

StyleSheet.configure({
    settings: {
        initialTheme: 'light',
    },
    breakpoints,
    themes: appThemes
})