Skip to content
Unistyles

For library authors

For library authors

Unistyles is highly extensible and can be utilized to build UI Kits and other kinds of projects.

Using Unistyles in your library

UnistylesRegistry can be invoked lazily after resolving user-required configurations, such as themes and plugins.

You can call UnistylesRegistry multiple times to override configurations. However, keep in mind that UnistylesRegistry makes a roundtrip to C++, which can add up to 1ms of additional setup time for Unistyles.

To manipulate your config without replacing it, you should use UnistylesRuntime.

Timing

Unistyles core does not have an asynchronous API. This means you can invoke UnistylesRegistry right before the first useStyle call:

import { UnistylesRegistry, useInitialTheme, useStyles } from 'react-native-unistyles'


export const App: React.FunctionComponent = () => {
    UnistylesRegistry
        .addConfig(...)
        .addBreakpoints(...)


    useInitialTheme('dark')


    const { styles } = useStyles(stylesheet)


    return (
        // your app
    )
}


// stylesheet

Plugins

You can extend Unistyles with your plugins that may transform the output to the desired style. Currently, Unistyles supports one lifecycle hook: onParsedStyle.

When does Unistyles re-render?

Unistyles only re-renders when it receives an event from C++. This means useStyles supports component memoization.

You should expect re-renders only when:

  • The theme changes.
  • The device orientation changes.
  • The screen size changes (web, macOS, Windows).
  • A plugin is registered or unregistered.
  • The variant changes.
  • Content size category (iOS), font scale (Android) changes.

No React Context

Unistyles does not use the React Context API. This means that users do not need to wrap their app with a Provider, reducing boilerplate and making your library more user-friendly.

New architecture ready

Unistyles handles all native configurations and supports new architecture, ensuring you don’t need to worry about Fabric or other low-level concepts.

Your UI Kit can support all React Native apps out of the box.

Minimum requirements

Unistyles is compatible with:

  • React Native version >=0.72
  • TypeScript >5.0
  • iOS 13.6+
  • Android 6+
  • macOS 10.14+
  • Windows 10.0.16299.0
  • tvOS 9.0+
  • visionOS 1.0+

CSS styles

There is ongoing work on custom CSS compiler that could entirely replace the React Native Web StyleSheet API, offering better Developer Experience (DX) and more predictable re-renders, e.g. with media queries.

Unistyles 2.0 was developed with this feature in mind. If you are interested, please open a discussion and share your use case.

Why choose Unistyles?

Unistyles offers a unique architecture not available in any other library. Built on top of the React Native StyleSheet API, it is fully compatible with it.

Without component abstraction, you have the freedom to build one. Unistyles supports various platforms and is easily extendable, particularly with plugins and variants.

With its smart architecture, you can maintain the same rendering time as the core.