Skip to content
Unistyles

Plugins

Plugins
All platforms
2.0.0

If you find that Unistyles lacks certain features, you can easily extend its functionality with plugins.

Plugins are functions that accept a style object and return a new style object. They are resolved in the order in which they were passed to the addConfig function in UnistylesRegistry.

Create a plugin

To create a plugin, you need to import the UnistylesPlugin type:

import type { UnistylesPlugin } from 'react-native-unistyles'

Then, create a function that conforms to this type:

export const myPlugin: UnistylesPlugin = {
    name: 'myPlugin',
    onParsedStyle: (key, styles, runtime) => {
        // parse styles here
    }
}

Your plugin must have a unique name; otherwise, it will be rejected from the registry.

onParsedStyle

The onParsedStyle function is called for every style object in the stylesheet passed to the useStyles hook. These objects are processed after Unistyles has finished parsing them, so they do not include:

  • variants
  • breakpoints
  • theme
  • media queries

For example:

const stylesheet = createStyleSheet(theme => ({
    container: {
        backgroundColor: theme.colors.primary,
        padding: 10
    },
    text: {
        color: theme.colors.typography,
        fontSize: {
            sm: 12,
            md: 14
        }
    }
}))

You will get, for instance, the following calls:

onParsedStyle('container', {
    backgroundColor: 'pink',
    padding: 10
}, runtime)


onParsedStyle('text', {
    color: '#000000',
    fontSize: 12
}, runtime)

Your function will be called twice: once for the container and once for text styles.

ArgumentTypeDescription
keystringName of the style eg. container or text
stylesStyleObjectStyle object for the corresponding key
runtimeUnistylesRuntimeRuntime with all required information about your configuration eg. breakpoint, themes etc.

Register plugins with UnistylesRegistry

Once you have your plugin, you can register it with UnistylesRegistry:

import { UnistylesRegistry } from 'react-native-unistyles'
import { myPlugin1 } from './myPlugin1'
import { myPlugin2 } from './myPlugin2'


UnistylesRegistry
    .addConfig({
        plugins: [myPlugin1, myPlugin2]
    })

Enable plugin at runtime

Unistyles offers the option to register plugins at runtime, allowing you to enable them only for specific components.

import { UnistylesRuntime } from 'react-native-unistyles'
import { myPlugin } from './myPlugin'


export const EnablePlugin: React.FunctionComponent = () => (
    <Button
        title="Add plugin"
        onPress={() => UnistylesRuntime.addPlugin(myPlugin)}
    />
)

Disable plugin at runtime

Similarly, you can disable plugins at runtime:

import { UnistylesRuntime } from 'react-native-unistyles'
import { myPlugin } from './myPlugin'


export const DisablePlugin: React.FunctionComponent = () => (
    <Button
        title="Remove plugin"
        onPress={() => UnistylesRuntime.removePlugin(myPlugin)}
    />
)

Get enabled plugins

You can also check which plugins are enabled at runtime:

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


export const GetPlugins: React.FunctionComponent = () => (
    <Button
        title="Get enabled plugins"
        onPress={() => {
            const plugins = UnistylesRuntime.enabledPlugins()


            // names of the plugins eg. myPlugin1, myPlugin2
            console.log(plugins)
        }}
    />
)

Example

Let’s build an example plugin that will add fontFamily based on the fontWeight.

export const fontWeightPlugin: UnistylesPlugin = {
    name: 'fontWeightPlugin',
    onParsedStyle: (_key, styles) => {
        if ('fontWeight' in styles) {
             // in this case we should add fontFamily
        }


        return styles
    }
}

We can use the onParsedStyle function to check if the fontWeight property is present in the style object. If so we will add a fontFamily:

export const fontWeightPlugin: UnistylesPlugin = {
    name: 'fontWeightPlugin',
    onParsedStyle: (_key, styles) => {
        if ('fontWeight' in styles) {
            switch (styles.fontWeight) {
                // add other weights
                case 'bold': {
                    styles.fontFamily = 'Roboto-Bold'
                }
                case '500':
                default: {
                    styles.fontFamily = 'Roboto-Regular'
                }
            }
        }


        return styles
    }
}

Looking for other inspirations?

High Contrast Plugin

Automatically adjust the contrast of your UI based on the theme.

Source code