This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 54).

Expo SystemUI

GitHub

Changelog

npm

A library that allows interacting with system UI elements.

Android

iOS

tvOS

Web

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

- 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

You can configure expo-system-ui using its built-in config plugin if you use config plugins in your project (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

{
  "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()`

Android

iOS

tvOS

Web

Gets the root view background color.

Returns:

Promise<ColorValue | 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)`

Android

iOS

tvOS

Web

Parameter	Type	Description
color	`null \| ColorValue`	Any valid CSS 3 (SVG) color.

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

Returns:

Promise<void>

Example

SystemUI.setBackgroundColorAsync("black");