Unistyles Runtime

Unistyles Runtime is a powerful feature that allows you to access platform specific values directly from JavaScript. It allows you to skip many dependencies and keep a lot of functionality under one object.

Usage

You can import UnistylesRuntime from react-native-unistyles:

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

and use it anywhere in your code, even outside a React component.

Available getters

Name	Type	Description
colorScheme	string	Get your device’s color scheme. Available options dark, light or unspecified
hasAdaptiveThemes	boolean	Indicates if you have enabled adaptive themes
themeName	string?	Name of the selected theme or undefined if you haven’t registered any theme. When read while rendering inside a ScopedTheme, it returns the scoped theme name
breakpoint	string?	Current breakpoint or undefined if you haven’t registered any
breakpoints	Object	Your registered breakpoints
screen	{width: number, height: number}	Screen dimensions
orientation	portrait or landscape	Current device orientation
isPortrait	boolean	Indicates if your device is in portrait mode
isLandscape	boolean	Indicates if your device is in landscape mode
contentSizeCategory	IOSContentSizeCategory, AndroidContentSizeCategory or WebContentSizeCategory	Your device’s content size category
insets	{ top: number, bottom: number, left: number, right: number, ime: number }	Device insets which are safe to put content into
statusBar	{width: number, height: number}	Status bar dimensions
navigationBar	{width: number, height: number}	Navigation bar dimensions (Android only)
pixelRatio	number	Pixel density of the device
fontScale	number	Font scale of the device
rtl	boolean	Indicates if the device is in RTL mode

Methods

Name	Type	Description
getTheme	(themeName?: string) => Theme	Get theme by name or current theme if name was not specified
setTheme	(themeName: string) => void	Change the current theme
setAdaptiveThemes	(enabled: boolean) => void	Toggle adaptive themes
updateTheme	(themeName: string, updater: (currentTheme: Theme) => Theme) => void	Update the theme at runtime
statusBar.setHidden	(hidden: boolean, animation?: ‘none’ | ‘fade’ | ‘slide’) => void	Show/hide status bar at runtime. animation is used on iOS
statusBar.setStyle	(style: StatusBarStyle, animated?: boolean) => void	Change status bar content style (StatusBarStyle.Default, StatusBarStyle.Light or StatusBarStyle.Dark)
navigationBar.setHidden	(hidden: boolean) => void	Show/hide navigation bar at runtime (Android only)
setImmersiveMode	(enabled: boolean) => void	Enable/disable immersive mode. Hides both status and navigation bars on Android, only the status bar on iOS (with fade animation)
setRootViewBackgroundColor	(color?: string) => void	Set root view background color. Accepts any React Native color, omit it to reset the color to transparent

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

UnistylesRuntime.statusBar.setStyle(StatusBarStyle.Light, true)
UnistylesRuntime.statusBar.setHidden(true, 'slide')

Note

On the web, statusBar and navigationBar always report 0 dimensions, and statusBar.setHidden, statusBar.setStyle, navigationBar.setHidden and setImmersiveMode do nothing. setRootViewBackgroundColor sets the background color of the html element.

RTL updates

rtl is updated at runtime:

• Android – when you call I18nManager.forceRTL or the app locale changes
• Web – when the dir attribute of the html element changes
• iOS – the value is read at app start, so changing it requires an app restart

Every change emits the Rtl dependency, so styles that use rt.rtl are recalculated automatically.

Why UnistylesRuntime doesn’t re-render my component?

You should think of UnistylesRuntime as a JavaScript object. It’s not a React hook, so it doesn’t re-render your component when eg. screen size or breakpoint changes. Instead it will return up to date value whenever you access it.

If you’re looking for a way to get fresh values and re-render your component, please check useUnistyles hook.

How to re-render my stylesheets based on UnistylesRuntime?

You can do that while accessing miniRuntime in your StyleSheet:

One example could be reading device width and height:

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

// your component

const style = StyleSheet.create((theme, rt) => ({
    container: {
        backgroundColor: theme.colors.background,
        width: rt.screen.width,
        height: rt.screen.height
    }
}))

Your container style will be auto-recalculated when screen changes.

Learn more on how Unistyles recalculates your styles.