Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 71 ยท Styling and Layout

Theming and Dark Mode

Add dark mode and theming to a React Native app with useColorScheme, the Appearance API, a theme context, design tokens and custom fonts loaded with expo-font.

Almost every phone has a system-wide dark mode, and users expect apps to follow it. Theming is also the answer to a related problem: since styles do not cascade in React Native (see Styling with StyleSheet), you need another way to share colors, spacing and fonts across hundreds of components. The usual answer is a theme object delivered through React context, with one small hook that tells you the current theme.

In this lesson you will read the system color scheme with useColorScheme and the Appearance API, build a theme provider that also lets the user override the system setting, organize design tokens, and load a custom font with expo-font. The native APIs are shown as read-only code, and the live examples are stand-ins that simulate the system setting with a switch.

Reading the system color scheme

React Native ships a hook for this:

TSX
import { useColorScheme, Text } from 'react-native';

export function SchemeLabel() {
  const scheme = useColorScheme(); // 'light' | 'dark' | null (depending on version and platform)
  return <Text>The system is in {scheme ?? 'an unknown'} mode</Text>;
}

The hook re-renders your component as soon as the user flips the setting, even while the app is open. Treat anything other than 'dark' as light, since the value can be null or 'unspecified' in some situations.

Two setup steps are easy to forget:

  • In an Expo project, set "userInterfaceStyle": "automatic" in the app config. With the default (light only), the app never switches, and useColorScheme keeps returning light. On Android this also requires the expo-system-ui package.
  • In a bare project, make sure the native side does not force a light theme (iOS UIUserInterfaceStyle in Info.plist, Android's Theme.AppCompat.DayNight).

The underlying API is Appearance, a module that works outside components:

TSX
import { Appearance } from 'react-native';

const now = Appearance.getColorScheme();

const subscription = Appearance.addChangeListener(({ colorScheme }) => {
  console.log('Scheme changed to', colorScheme);
});
// later: subscription.remove();

Appearance.setColorScheme('dark'); // force dark; pass null to follow the system again

Appearance.setColorScheme overrides the app's scheme, which is useful when you offer a manual setting. You then also get the correct native look for built-in components such as alerts and keyboards.

Design tokens

Do not scatter hex codes through your files. A design token is a named value that carries a meaning, such as background or textMuted, rather than a color. Give each theme the same set of token names with different values:

TSX
export const lightTheme = {
  colors: {
    background: '#ffffff',
    surface: '#f4f4f5',
    text: '#18181b',
    textMuted: '#52525b',
    primary: '#4f46e5',
    border: '#e4e4e7',
  },
  spacing: { xs: 4, sm: 8, md: 16, lg: 24 },
  radius: { sm: 6, md: 12 },
};

export const darkTheme = {
  ...lightTheme,
  colors: {
    background: '#09090b',
    surface: '#18181b',
    text: '#fafafa',
    textMuted: '#a1a1aa',
    primary: '#818cf8',
    border: '#3f3f46',
  },
};

Components ask for colors.surface, never '#f4f4f5'. Adding a new theme later (high contrast, a brand variant) is then one new object. Dark themes are rarely a simple inversion: pure black text on pure white feels harsh in the other direction, so dark palettes typically use slightly softened colors and lighter shades of the brand color so contrast stays readable. Check contrast ratios in both themes (see Accessibility in React Native).

One theme, many components

Tokens Names such as surface and textMuted.
Two palettes Same names, different values.
Context One provider, no prop drilling.
1 / 2

A theme context

A provider decides which theme is active, and a hook gives components access to it. The decision has two inputs: the user's preference ('system', 'light' or 'dark') and the actual system scheme.

TSX
import { createContext, useContext, useMemo, useState, type ReactNode } from 'react';
import { useColorScheme } from 'react-native';

type Preference = 'system' | 'light' | 'dark';

const ThemeContext = createContext({
  theme: lightTheme,
  scheme: 'light' as 'light' | 'dark',
  preference: 'system' as Preference,
  setPreference: (_p: Preference) => {},
});

export function ThemeProvider({ children }: { children: ReactNode }) {
  const system = useColorScheme();
  const [preference, setPreference] = useState<Preference>('system');

  const scheme = preference === 'system' ? (system === 'dark' ? 'dark' : 'light') : preference;
  const value = useMemo(
    () => ({ theme: scheme === 'dark' ? darkTheme : lightTheme, scheme, preference, setPreference }),
    [scheme, preference],
  );

  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

export const useTheme = () => useContext(ThemeContext);

Notice the one place that resolves the final scheme: the line with preference === 'system' ? ... : preference. If you saved the user's preference with the techniques from Storing Data: AsyncStorage, MMKV and SecureStore, you would initialize preference from storage so the choice survives restarts.

The core logic is a pure function, which makes it easy to test. Here it is as a stand-in you can run:

JS Resolving the active theme (plain JavaScript)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The third case shows why the function compares against 'dark' instead of testing for 'light': a null system value safely falls back to light.

Using the theme in components

Components read tokens through the hook and create styles from them. Because tokens change at run time, the styles are built inside the component (or inside a helper like makeStyles(theme) wrapped in useMemo), not in a module-level StyleSheet.create:

TSX
function Card({ title }: { title: string }) {
  const { theme } = useTheme();
  return (
    <View style={{ backgroundColor: theme.colors.surface, padding: theme.spacing.md, borderRadius: theme.radius.md, borderColor: theme.colors.border, borderWidth: 1 }}>
      <Text style={{ color: theme.colors.text, fontSize: 18 }}>{title}</Text>
    </View>
  );
}

Many teams go one step further and wrap the basics (ThemedText, ThemedView) so that a screen author rarely touches colors directly. That brings back some of the "inherit from parent" convenience in an explicit way. Also remember the navigation bar, status bar and keyboard: React Navigation takes its own theme object, and StatusBar needs style="light" or "dark" to stay readable on your background.

A theme provider demo

The stand-in below renders a small screen. The "system" setting is simulated with a dropdown, because a browser preview cannot read your phone's scheme. Change the user preference and the simulated system value and watch which theme wins.

Stand-in: a theme provider with a system option

With the preference on "system", flipping the simulated phone setting changes the whole screen. Pick "dark" explicitly and the phone setting no longer matters, which is exactly what a manual override should do.

Custom fonts with expo-font

Fonts are part of a theme too. In Expo you load font files with expo-font and hold the first screen until they are ready, otherwise the text jumps from the system font to yours:

TSX
import { useFonts } from 'expo-font';
import * as SplashScreen from 'expo-splash-screen';
import { useEffect } from 'react';

SplashScreen.preventAutoHideAsync();

export default function Root() {
  const [loaded, error] = useFonts({
    Inter: require('./assets/fonts/Inter-Regular.ttf'),
    'Inter-Bold': require('./assets/fonts/Inter-Bold.ttf'),
  });

  useEffect(() => {
    if (loaded || error) SplashScreen.hideAsync();
  }, [loaded, error]);

  if (!loaded && !error) return null;
  return <App />;
}

Use the registered names in styles: fontFamily: 'Inter' and fontFamily: 'Inter-Bold'. On both platforms prefer separate font files per weight with matching fontFamily names rather than relying on fontWeight, since weights for custom fonts are inconsistent between iOS and Android. Add the font family names to your theme (fonts: { regular: 'Inter', bold: 'Inter-Bold' }) so changing the typeface is a one-line edit.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In an Expo app, useColorScheme always returns 'light' even after you switch the phone to dark mode. What should you check first?

    The default app config locks the interface style to light. Setting userInterfaceStyle to 'automatic' (plus expo-system-ui on Android) lets the app follow the system.
  2. 2. Why build theme-dependent styles inside the component instead of in a module-level StyleSheet.create?

    A module-level style object is computed once. Theme colors depend on state, so the styles must be derived during render (optionally memoized).
  3. 3. What is a design token?

    Tokens give values semantic names so components say 'surface' and the theme decides which color that is.
  4. 4. A user picks 'dark' in your app's settings while the phone is in light mode. Which theme should the app show?

    Only the 'system' preference defers to useColorScheme. 'light' and 'dark' are explicit choices that take priority.

Summary

  • useColorScheme (and Appearance) report the system scheme; treat anything other than 'dark' as light, and set userInterfaceStyle to automatic in Expo.
  • Design tokens give colors, spacing and radii semantic names, and each theme supplies the same names with different values.
  • A theme provider resolves one final scheme from the user's preference (system, light, dark) and the system value, and exposes it with a hook.
  • Build theme-dependent styles during render, since module-level styles do not react to changes; sync StatusBar and navigation themes too.
  • Load fonts with useFonts, keep the splash screen up until they are ready, and register one family name per weight.
  • The demos simulate the phone's setting with a dropdown; they illustrate the logic, not the native API.

Next: Styling Libraries and Design Systems