Expo System UI

Expo System UI adds support for locking the user interface (appearance) and updating the root view background color. It provides asynchronous functions to set and get the root view background color across different platforms including React Native and web, with support for any valid CSS 3 (SVG) color values.

Package Information

• Package Name: expo-system-ui
• Package Type: npm
• Language: TypeScript
• Installation: npx expo install expo-system-ui

Core Imports

import { setBackgroundColorAsync, getBackgroundColorAsync } from "expo-system-ui";

For CommonJS:

const { setBackgroundColorAsync, getBackgroundColorAsync } = require("expo-system-ui");

Basic Usage

import { setBackgroundColorAsync, getBackgroundColorAsync } from "expo-system-ui";

// Set the root view background color
await setBackgroundColorAsync("black");
await setBackgroundColorAsync("#FF5733");
await setBackgroundColorAsync("rgba(255, 87, 51, 0.8)");

// Get the current root view background color
const currentColor = await getBackgroundColorAsync();
console.log(currentColor); // Returns color in hex format or null

// Clear the background color (set to null)
await setBackgroundColorAsync(null);

Architecture

Expo System UI provides a unified API that works across different platforms:

• React Native (iOS/Android): Uses native modules via expo-modules-core
• Web: Directly manipulates document.body.style.backgroundColor
• Color Processing: Handles platform-specific color processing and normalization
• Expo Config Plugin: Provides build-time configuration for native platforms

Capabilities

Background Color Management

Asynchronous functions for setting and getting the root view background color with cross-platform support.

/**
 * Changes the root view background color.
 * Call this function in the root file outside of your component.
 * @param color Any valid CSS 3 (SVG) color or null to clear
 * @returns Promise that resolves when the color is set
 */
function setBackgroundColorAsync(color: ColorValue | null): Promise<void>;

/**
 * Gets the root view background color.
 * @returns Promise resolving to current root view background color in hex format, or null if not set
 */
function getBackgroundColorAsync(): Promise<ColorValue | null>;

Usage Examples:

import { setBackgroundColorAsync, getBackgroundColorAsync } from "expo-system-ui";

// Set various color formats
await setBackgroundColorAsync("red");           // Named color
await setBackgroundColorAsync("#FF0000");       // Hex color
await setBackgroundColorAsync("rgb(255,0,0)");  // RGB color
await setBackgroundColorAsync("rgba(255,0,0,0.5)"); // RGBA color
await setBackgroundColorAsync("hsl(0,100%,50%)"); // HSL color

// Clear the background color
await setBackgroundColorAsync(null);

// Get current color
const color = await getBackgroundColorAsync();
if (color) {
  console.log(`Current background color: ${color}`);
} else {
  console.log("No background color set");
}

Expo Config Plugin

Configuration plugin for automatic native setup during build process.

/**
 * Expo config plugin for system UI configuration
 * Applies Android and iOS native configuration changes automatically
 */
const systemUIPlugin: ConfigPlugin<void>;

Plugin Usage:

Add to your app.config.js or app.config.ts:

module.exports = {
  name: "my-app",
  plugins: [
    "expo-system-ui" // Automatically applies native configuration
  ]
};

The plugin handles:

• Android root view background color configuration
• Android user interface style settings
• iOS root view background color configuration
• iOS user interface style settings

Types

/**
 * React Native color value type supporting various color formats
 * Imported from react-native package
 */
type ColorValue = string | number;

Valid color formats include:

• Named colors: "red", "blue", "transparent"
• Hex colors: "#FF0000", "#F00"
• RGB/RGBA: "rgb(255,0,0)", "rgba(255,0,0,0.5)"
• HSL/HSLA: "hsl(0,100%,50%)", "hsla(0,100%,50%,0.5)"

Platform Support

• Expo Managed Workflow: Full support with automatic configuration
• Expo Bare Workflow: Requires manual setup of expo-modules-core
• React Native: Supported with expo-modules-core setup
• Web (react-native-web): Full support with DOM manipulation
• Android: Native module implementation
• iOS: Native module implementation

Setup Requirements

Managed Expo Projects

No additional setup required - the plugin handles native configuration automatically.

Bare React Native Projects

Ensure you have the native expo package setup:

1. Install expo-modules-core: npx install-expo-modules
2. Follow the expo-modules installation guide
3. Add the plugin to your app.config.js if you want automatic native configuration

Error Handling

The functions handle color processing errors gracefully:

• Invalid colors may be processed by the underlying platform color parser
• On web, invalid colors fall back to browser defaults
• Network or native module errors are propagated as Promise rejections

try {
  await setBackgroundColorAsync("invalid-color");
} catch (error) {
  console.error("Failed to set background color:", error);
}