Skip to content
react-native-unistyles

Configuration

Configure Unistyles

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

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
}

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 three 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 CSS variables (defaults to true) 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 etc.


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


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

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!

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