React Native Dark Mode and Theming: A Systematic Approach

1. Why hardcoded colors are a theming problem

In many React Native codebases, you'll see color values like backgroundColor: '#ffffff' scattered directly across dozens of components. As long as only one static color scheme exists, this works fine. The moment dark mode and theming are required, though, every single occurrence has to be found and adjusted manually, which in larger apps quickly means hundreds of spots and guarantees inconsistencies.

The real problem isn't dark mode itself, it's missing indirection. A component should never know whether "white" or "dark gray" is meant, only that it needs the background color for a card. Systematic dark mode and theming introduces exactly this layer of indirection, so a single change to a token updates every affected component at once.

The effort of retrofitting dark mode and theming into an existing app grows with every week that new components keep using hardcoded colors. An early architectural decision in favor of design tokens therefore pays off over the entire project lifetime, not just at the first dark mode release.

2. Design tokens as the single source of truth

Design tokens are named values for color, spacing, and typography defined independently of a specific platform or a specific theme. Instead of using #1e1b4b directly, code references a semantic token such as background.primary, which resolves to different concrete values depending on the active theme. This pattern is the foundation of any robust dark mode and theming system.

What matters is semantic rather than descriptive naming: text.primary instead of gray900, because the concrete color behind the token changes in dark mode while the name stays stable. A component using colors.text.primary never needs to change on a theme switch, because the mapping lives entirely in the token file.

{
  "light": {
    "background": { "primary": "#ffffff", "secondary": "#f1f5f9" },
    "text": { "primary": "#0f172a", "secondary": "#475569" },
    "accent": { "default": "#4338ca" }
  },
  "dark": {
    "background": { "primary": "#0f172a", "secondary": "#1e293b" },
    "text": { "primary": "#f1f5f9", "secondary": "#94a3b8" },
    "accent": { "default": "#818cf8" }
  }
}

3. useColorScheme: detecting the OS setting

The React Native hook useColorScheme() returns the currently active system mode, either 'light', 'dark', or null if the operating system reports no preference. It reacts live to changes: if the user switches between light and dark mode at the OS level while the app runs in the background, the value updates automatically the next time the app comes to the foreground.

For a clean dark mode and theming system, useColorScheme() alone isn't enough, because many apps also want to offer users a manual override option independent of the system setting. But the hook provides the foundation on which a custom theme state is built, one that combines system preference and manual override.

4. The ThemeProvider with React Context

A ThemeProvider makes design tokens and the current theme name available to the entire component hierarchy via React Context. Every component accesses the current token values through a useTheme() hook instead of implementing its own theme detection logic. This centralization is the core of any maintainable dark mode and theming approach.

It's important that the context provider sits as high as possible in the component tree, usually right below the root element, so navigation headers and modals can consistently access the same tokens. A changing context value automatically triggers a re-render of all consuming components, which propagates theme switches without manual intervention.

// theme/ThemeProvider.tsx — centralizes theme state and design tokens
import React, { createContext, useContext, useMemo, useState, useEffect } from 'react';
import { useColorScheme } from 'react-native';
import tokens from './tokens.json';

type ThemeMode = 'light' | 'dark' | 'system';
type ThemeContextValue = {
  colors: typeof tokens.light;
  mode: ThemeMode;
  setMode: (mode: ThemeMode) => void;
};

const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const systemScheme = useColorScheme();
  const [mode, setMode] = useState<ThemeMode>('system');

  const resolvedScheme = mode === 'system' ? (systemScheme ?? 'light') : mode;
  const colors = tokens[resolvedScheme];

  const value = useMemo(() => ({ colors, mode, setMode }), [colors, mode]);

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

export function useTheme() {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error('useTheme must be used within a ThemeProvider');
  return ctx;
}

5. Manual override: light, dark, system

Users today typically expect three options: follow the system, always light mode, always dark mode. The third state, "system," isn't an additional theme, it's an instruction to keep following useColorScheme() instead of a fixed value. Modeling this distinction cleanly in the state model prevents dark mode and theming logic from branching unnecessarily.

The settings UI itself is usually a simple segmented control with three options that calls the setMode() setter from the ThemeProvider. It's important that this setting is persisted, not just held in memory, so the chosen mode survives an app restart.

6. Persistence with AsyncStorage

Without persistence, every app start would reset the theme mode to "system," even if a user had explicitly forced dark mode. AsyncStorage stores the chosen mode as a simple string and reads it at app start, before the first component renders, to avoid a brief flash of the wrong theme.

Loading from AsyncStorage is asynchronous, which means the app briefly starts with a default theme before the stored value is available. For a flicker-free dark mode and theming experience, this brief loading phase is usually covered with a neutral splash screen instead of showing the UI with the wrong theme.

#!/usr/bin/env bash
# Install AsyncStorage for theme mode persistence
npm install @react-native-async-storage/async-storage
cd ios && pod install && cd ..
echo "AsyncStorage installed for theme persistence"

7. Images, icons, and status bar per theme

Not just colors, image assets also need to be swapped based on theme: a logo with dark text on a light background becomes unreadable in dark mode. The robust solution stores two variants for critical assets and picks between them using the same useTheme() hook, instead of attempting CSS filters or runtime post-processing.

The status bar also needs to stay in sync with the theme: StatusBar barStyle="light-content" in dark mode, "dark-content" in light mode. If this is forgotten, the clock and battery indicator visually disappears against the light background, a commonly overlooked bug when retrofitting dark mode and theming.

// ios/Info.plist — UIUserInterfaceStyle touch point for forcing appearance
// Leaving this key unset lets the app follow useColorScheme() dynamically.
// Setting it to "Dark" or "Light" would force the OS-level appearance
// and should only be used for apps that intentionally opt out of system theming.

8. Avoiding flicker and testing style caches

A common symptom of broken dark mode and theming is a brief flash of the wrong theme at app start or theme switch. The cause is usually that styles created with StyleSheet.create() are computed once at module initialization instead of being recreated on every render with the current token values.

The fix: style objects that depend on theme tokens must not be predefined at the module level with StyleSheet.create(), but instead computed inside the component with useMemo() from the current colors. A test that deliberately switches between light and dark and runs a screenshot comparison reliably catches this kind of caching bug.

9. Theming approaches compared

There are several established ways to implement dark mode and theming in React Native, each with different trade-offs between flexibility, bundle size, and learning curve.

For most React Native projects, the combination of useColorScheme() and a custom Context-based ThemeProvider is the most pragmatic entry into dark mode and theming, without an extra runtime dependency. NativeWind pays off when Tailwind classes are already part of the stack, Restyle shines for strictly typed design systems.

10. Summary

Systematic dark mode and theming in React Native starts with design tokens as the single source of truth, not with hardcoded color values scattered across individual components. useColorScheme() detects the system preference, a Context-based ThemeProvider makes the active tokens available to the entire app, and a manual override between light, dark, and system covers most users' expectations.

Persistence with AsyncStorage ensures the chosen mode survives an app restart, while careful handling of image assets, status bar, and style computation prevents flicker and visual inconsistencies. Planning these building blocks from the start saves a costly retrofit once dark mode becomes a hard requirement.

11. FAQ: React Native Dark Mode and Theming