Solution

You'll treat the browser's dark-scheme media query as a tiny external signal: synchronize React state from its current snapshot, subscribe to future changes, and disconnect that subscription when the component leaves.

The problem, in plain English

The user's color-scheme preference does not belong to your component. It lives in the browser and can change while the component is mounted—for example, when the operating system switches to a scheduled night theme. Reading the preference once answers “what is it now?” but not “tell me when it changes.” The hook needs both halves: the media query's current matches value and its change event.

The mental model

Picture a three-link pipeline. The operating system owns the setting. matchMedia('(prefers-color-scheme: dark)') exposes that setting as a MediaQueryList. React state mirrors the list so a component re-renders whenever the list reports a different value.

A first attempt

The tempting version reads matches in the state initializer and stops:

const { useState } = require('react');

function useDarkMode(defaultValue = false) {
  const [isDarkMode] = useState(() => {
    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
      return Boolean(defaultValue);
    }
    return window.matchMedia('(prefers-color-scheme: dark)').matches;
  });

  return isDarkMode;
}

It passes an initial light-or-dark check, which makes the bug easy to miss. But a state initializer runs once. When the browser later changes from light to dark, nothing calls a setter, so React keeps returning the old value forever.

The working solution

const { useEffect, useState } = require('react');

const DARK_MODE_QUERY = '(prefers-color-scheme: dark)';

function useDarkMode(defaultValue = false) {
  // Starting from a caller-controlled value is safe when this render happens
  // without browser APIs, as it does during server rendering.
  const [isDarkMode, setIsDarkMode] = useState(Boolean(defaultValue));

  useEffect(() => {
    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
      return undefined;
    }

    const mediaQuery = window.matchMedia(DARK_MODE_QUERY);
    const handleChange = (event) => setIsDarkMode(event.matches);

    // The preference may differ from the server/default snapshot by mount time.
    setIsDarkMode(mediaQuery.matches);
    mediaQuery.addEventListener('change', handleChange);

    return () => mediaQuery.removeEventListener('change', handleChange);
  }, []);

  return isDarkMode;
}

module.exports = { useDarkMode };

The state now has a setter, and the effect owns the entire browser subscription. It obtains one MediaQueryList, immediately reconciles state from its current matches snapshot, attaches one handler, and closes over that same list and handler for cleanup. The empty dependency array is appropriate because the query is a fixed constant and the subscription should live for exactly one mount.

Walking through one call

Suppose the server/default value is light (false), but the browser currently prefers dark:

1. Render safely. useState(Boolean(false)) returns false without touching window, so this step is safe even outside a browser.
2. Mount in the browser. The effect calls matchMedia('(prefers-color-scheme: dark)') and receives a list whose matches is true.
3. Reconcile. setIsDarkMode(true) updates the stale default, so the component re-renders with dark mode active.
4. Subscribe. The effect registers handleChange for the list's change event.
5. System switches to light. The browser emits an event with matches: false; the handler calls setIsDarkMode(false), producing the next render.
6. Unmount. Cleanup removes that exact handler from that exact MediaQueryList, so the abandoned component cannot receive later changes.

Complexity

Mounting and each preference change take O(1) time and the hook stores O(1) state. It creates one media-query subscription per mounted hook instance.

Gotchas

• Reading matches once. A correct initial value can hide the fact that the hook never updates. Fix: subscribe to the MediaQueryList object's change event and drive a state setter from event.matches.
• Listening on window. The preference change belongs to the returned MediaQueryList, not to a generic window event. Fix: call mediaQuery.addEventListener('change', handler).
• Recreating the query on every render. Calling matchMedia during render and placing that object in effect dependencies can tear down and rebuild the listener repeatedly. Fix: acquire it inside a mount-only effect.
• Removing a different function. removeEventListener('change', () => ...) creates a new function and leaves the original subscribed. Fix: name handleChange inside the effect and pass the same reference to add and remove.
• Touching window before the effect. A state initializer that calls window.matchMedia throws during server rendering and can make server/client markup disagree. Fix: initialize from defaultValue, then reconcile after mount.

Going further

• User override and persistence. Layer a three-state preference—'light', 'dark', or 'system'—over this signal, persist the explicit choice, and fall back to the media query only in system mode.
• Reusable media-query hook. Extract the subscription into useMediaQuery(query, defaultValue) and implement dark mode as useMediaQuery('(prefers-color-scheme: dark)').
• External-store semantics. For a shared subscription with snapshot consistency across concurrent rendering, model MediaQueryList through useSyncExternalStore instead of giving each hook instance its own state and listener.