Skip to main content

​
expo-system-ui

Version: 55.0.6 Interact with system UI elements like the background color of the root view.

​
Installation

npx expo install expo-system-ui

​
Usage

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

// Set root view background color
await SystemUI.setBackgroundColorAsync('#000000');

// Get current background color
const color = await SystemUI.getBackgroundColorAsync();

​
API Reference

​
Methods

​
SystemUI.setBackgroundColorAsync(color)
(color: string) => Promise<void>
Sets the root view background color
await SystemUI.setBackgroundColorAsync('#FF0000');
await SystemUI.setBackgroundColorAsync('rgba(255, 0, 0, 0.5)');
This affects the background color visible during screen transitions or when content doesn’t fill the screen.
​
SystemUI.getBackgroundColorAsync()
() => Promise<string | null>
Gets the current root view background color
const color = await SystemUI.getBackgroundColorAsync();
console.log('Background color:', color);

​
Examples

​
Dark Mode Background

import * as SystemUI from 'expo-system-ui';
import { useEffect } from 'react';
import { useColorScheme } from 'react-native';

function App() {
  const colorScheme = useColorScheme();

  useEffect(() => {
    const setSystemColors = async () => {
      if (colorScheme === 'dark') {
        await SystemUI.setBackgroundColorAsync('#000000');
      } else {
        await SystemUI.setBackgroundColorAsync('#FFFFFF');
      }
    };

    setSystemColors();
  }, [colorScheme]);

  return <YourApp />;
}

​
Custom Themed Background

import * as SystemUI from 'expo-system-ui';
import { useEffect } from 'react';

function ThemedApp({ theme }) {
  useEffect(() => {
    SystemUI.setBackgroundColorAsync(theme.backgroundColor);
  }, [theme]);

  return <YourApp />;
}

​
Match Navigation Background

import * as SystemUI from 'expo-system-ui';
import { NavigationContainer, DefaultTheme, DarkTheme } from '@react-navigation/native';
import { useColorScheme } from 'react-native';
import { useEffect } from 'react';

function App() {
  const colorScheme = useColorScheme();
  const theme = colorScheme === 'dark' ? DarkTheme : DefaultTheme;

  useEffect(() => {
    SystemUI.setBackgroundColorAsync(theme.colors.background);
  }, [theme]);

  return (
    <NavigationContainer theme={theme}>
      {/* Your navigation */}
    </NavigationContainer>
  );
}

​
Platform Support

PlatformSupportedNotes
iOS✅Root view background
Android✅Root view background
Web✅Document body background

​
Configuration

You can also set the initial background color in app.json: 
{
  "expo": {
    "backgroundColor": "#FFFFFF",
    "ios": {
      "backgroundColor": "#FFFFFF"
    },
    "android": {
      "backgroundColor": "#FFFFFF"
    }
  }
}

​
Best Practices

  1. Match App Theme: Keep system UI colors consistent with your app theme
  2. Handle Dark Mode: Update system UI when color scheme changes
  3. Initial Color: Set via app.json to avoid flash on launch
  4. Smooth Transitions: Update system UI before screen transitions

​
Resources