Source: https://docs.expo.dev/versions/v54.0.0/sdk/system-ui

Hide navigation

Search

Ctrl K

Home Guides EAS Reference Learn

Reference version

SDK 54

Archive Expo Snack Discord and Forums Newsletter

Expo SystemUI

GitHub Changelog npm

A library that allows interacting with system UI elements.

GitHub Changelog npm

Android

iOS

tvOS

Web

Bundled version:

~6.0.8

Copy page

---

expo-system-ui enables you to interact with UI elements that fall outside of the React tree. Specifically the root view background color, and locking the user interface style globally on Android.

Installation

---

Terminal

Copy

- npx expo install expo-system-ui

If you are installing this in an existing React Native app , make sure to install expo in your project.

Configuration in app config

---

Enable the expo-system-ui config plugin when you use Continuous Native Generation (CNG) . The plugin allows you to configure userInterfaceStyle on Android and backgroundColor on iOS properties from app config . These properties cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

Example app.json with config plugin

app.json

Copy

{ "expo": { "backgroundColor": "#ffffff", "userInterfaceStyle": "light", "ios": { "backgroundColor": "#ffffff", } "android": { "userInterfaceStyle": "light" }, "plugins": ["expo-system-ui"], } }

Are you using this library in an existing React Native app?

If you're not using Continuous Native Generation (CNG ) or you're using native android and ios project manually, then you need to add the following configuration to your native project:

Android

To apply userInterfaceStyle on Android, you need to add the expo_system_ui_user_interface_style configuration android/app/src/main/res/values/strings.xml:

<resources> <!-- ... --> <string name="expo_system_ui_user_interface_style" translatable="false">light</string> <!-- or dark --> </resources>

iOS

To apply backgroundColor on iOS, you need to add the UIUserInterfaceStyle configuration in ios/your-app/Info.plist:

<plist> <dict> <!-- ... --> <key>UIUserInterfaceStyle</key> <string>Light</string> <!-- or Dark --> </dict> </plist>

API

---

import * as SystemUI from 'expo-system-ui';

Methods

---

SystemUI.getBackgroundColorAsync()

Gets the root view background color.

Returns:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <[ColorValue](https://reactnative.dev/docs/colors) | null>

Current root view background color in hex format. Returns null if the background color is not set.

Example

const color = await SystemUI.getBackgroundColorAsync();

SystemUI.setBackgroundColorAsync(color)

| Parameter | Type | Description | | --- | --- | --- | | color | null \| [ColorValue](https://reactnative.dev/docs/colors) | Any valid CSS 3 (SVG) color<br>. |

Changes the root view background color. Call this function in the root file outside of your component.

Returns:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <void>

Example

SystemUI.setBackgroundColorAsync("black");