React Context for Theme State

Start by calling createContext() with a default value that matches your context shape: const ThemeContext = createContext({ theme: 'light', toggleTheme: () => {} }). The default value is used only when a component reads the context without a parent Provider, which helps with testing isolated components.

The ThemeProvider component is a wrapper that holds all theme logic. It reads the system preference on mount, manages the theme state, provides a toggleTheme function, and wraps children in ThemeContext.Provider value={{ theme, toggleTheme }}. Place it near the top of your component tree.

Any descendant component can access the theme by calling useContext(ThemeContext). This returns the current context value including theme and toggleTheme. The component automatically re-renders when the theme changes, keeping it always in sync without prop drilling.

CSS variables depend on a data-theme attribute on the root element. In ThemeProvider, add a useEffect that runs whenever theme changes: document.documentElement.setAttribute('data-theme', theme). This bridges the React state and the CSS layer seamlessly.

To persist the user choice across page reloads, write to localStorage whenever the theme changes: localStorage.setItem('theme', theme). You can encapsulate this logic in a useLocalStorage custom hook that returns a state-like pair and persists every update automatically.

When initializing the theme state, read from localStorage first: localStorage.getItem('theme'). If no stored value exists, fall back to the system preference via window.matchMedia('(prefers-color-scheme: dark)').matches. This initialization runs only once on mount.

The correct priority from highest to lowest is: stored user preference in localStorage, then system OS preference, then a hard-coded default (usually light). This order ensures the user always has final control while still respecting their OS configuration if they have not explicitly chosen in the app.

Directly calling useContext(ThemeContext) in every component exposes implementation details. Instead, export a useTheme hook: function useTheme() { return useContext(ThemeContext); }. Components now import useTheme and call it without knowing about the underlying context.

The toggleTheme function switches between light and dark: setTheme(prev => prev === 'light' ? 'dark' : 'light'). Expose it through context so any button anywhere in the tree can trigger it. The state lives in one place; the toggle logic is shared everywhere.

The context value object is recreated on every render of ThemeProvider. Wrap it in useMemo to prevent unnecessary re-renders of all context consumers: const value = useMemo(() => ({ theme, toggleTheme }), [theme]). This is a common performance optimization for context providers.

In tests, wrap renders in a custom renderWithTheme utility that uses ThemeProvider as a wrapper. You can also create a light mock context for isolated testing: ThemeContext.Provider value={{ theme: 'dark', toggleTheme: jest.fn() }}. This lets you test components in a specific theme state.

What is the correct priority order for initializing the app theme, from highest to lowest priority?

Create a ThemeContext and a ThemeProvider that manages theme state, syncs to localStorage, and sets data-theme on the document. Use a useTheme convenience hook for clean consumption. Priority order is: stored preference, then system preference, then default.