Solution

The provider keeps theme state local to one subtree and exposes a small, stable interface to its descendants.

The problem, in plain English

A toolbar several levels below the app shell needs the current theme and a way to change it. Passing those values through every component couples unrelated layers to theme state. React context lets a provider publish one value to any descendant that asks for it.

The mental model

Treat each provider as the boundary of a theme zone. Descendants read the closest zone, while components outside every zone receive an error instead of an ambiguous fallback.

A first attempt

function ThemeProvider({ initialTheme = 'light', children }) {
  const [theme, setTheme] = React.useState(initialTheme);
  const toggleTheme = () => setTheme(theme === 'dark' ? 'light' : 'dark');
  const value = { theme, setTheme, toggleTheme };
  return React.createElement(ThemeContext.Provider, { value }, children);
}

This renders the right value at first, but it creates a new toggle function and context object on every provider render. Its toggle also closes over one rendered value, so two calls batched before the next render both calculate from the same stale theme. Consumers receive needless identity changes even when the theme stays put.

The working solution

const React = require('react');

const ThemeContext = React.createContext(undefined);

function ThemeProvider({ initialTheme = 'light', children }) {
  const [theme, setTheme] = React.useState(initialTheme);

  const toggleTheme = React.useCallback(() => {
    setTheme((current) => (current === 'dark' ? 'light' : 'dark'));
  }, []);

  const value = React.useMemo(
    () => ({ theme, setTheme, toggleTheme }),
    [theme, toggleTheme],
  );

  return React.createElement(ThemeContext.Provider, { value }, children);
}

function useTheme() {
  const value = React.useContext(ThemeContext);
  if (value === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return value;
}

module.exports = { ThemeProvider, useTheme };

The functional updater reads the current queued state, so consecutive toggles compose even when React batches them. useCallback preserves the toggle's identity, and React already preserves the identity of setTheme. useMemo can therefore reuse the whole context object until theme changes.

Walking through one call

Mount <ThemeProvider initialTheme="light"> around a toolbar. useState captures light on the first mount, and useTheme returns { theme: 'light', setTheme, toggleTheme }. Call toggleTheme() twice in one event: the first updater receives light and queues dark; the second receives that queued dark and returns light. Because the final state equals the starting state, the memoized public value remains valid.

Now place a second provider with initialTheme="dark" around one nested panel. That panel reads and updates the inner state; its sibling still reads the outer light state.

Gotchas

• Using a fallback context object — a default value hides a missing provider and lets updates fail later; use undefined as a sentinel and throw in useTheme.
• Copying initialTheme in an effect — an effect keyed on the prop resets user changes whenever the parent rerenders with a new value; pass it only to useState.
• Closing over theme in the toggle — batched toggles all read the same render snapshot; use setTheme(current => ...) so each update receives the queued result.
• Skipping memoization — { theme, setTheme, toggleTheme } is a new object on every provider render; memoize it after stabilizing the functions.
• Adding a wrapper element — a provider does not need a <div> and should not alter layout; return the context provider around children directly.

Going further

• Persist explicit theme choices to storage, with a server-safe initialization strategy.
• Read prefers-color-scheme when no explicit choice exists and subscribe to system changes.
• Split state and actions into separate contexts only after measuring consumers that need different update behavior.