Solution

You'll mirror the browser's reduced-motion signal into React state, listen for later changes, and release the listener when the component unmounts.

The problem, in plain English

Some people enable reduced motion because animated zooms, parallax, or rapid transitions can cause discomfort. The preference belongs to the browser, not to your component. A hook can read that external value, but a one-time read becomes stale if the person changes the setting while your page remains open. Your implementation therefore needs both a current snapshot and a subscription.

The mental model

Treat the MediaQueryList as a small external signal. Its matches property is the current snapshot, and its change event announces later snapshots. React state mirrors those values so consumers render the current preference.

A first attempt

The tempting version reads the media query in the state initializer:

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

function usePrefersReducedMotion() {
  const [reduceMotion] = useState(() =>
    window.matchMedia('(prefers-reduced-motion: reduce)').matches,
  );
  return reduceMotion;
}

This can return the right value at mount, so the missing behavior is easy to overlook. The initializer never runs again, which means no later preference change reaches React. It also reads window during render and throws when the browser API is absent.

The working solution

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

const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';

function usePrefersReducedMotion(defaultValue = false) {
  // The first render must not depend on browser-only APIs.
  const [prefersReducedMotion, setPrefersReducedMotion] = useState(
    Boolean(defaultValue),
  );

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

    const mediaQuery = window.matchMedia(REDUCED_MOTION_QUERY);
    const handleChange = (event) => setPrefersReducedMotion(event.matches);

    // The browser snapshot is authoritative once the effect can read it.
    setPrefersReducedMotion(mediaQuery.matches);
    mediaQuery.addEventListener('change', handleChange);

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

  return prefersReducedMotion;
}

module.exports = { usePrefersReducedMotion };

The initial state uses only caller data, so rendering stays safe without window. The mount-only effect acquires one MediaQueryList, reconciles from its authoritative matches value, and registers one named handler. Cleanup closes over that same query object and handler, which gives removeEventListener the exact pair used for subscription.

Walking through one call

Suppose defaultValue is false, but the browser already has reduced motion enabled:

1. Render safely. Boolean(false) produces false without reading window.
2. Mount. The effect calls matchMedia('(prefers-reduced-motion: reduce)') once.
3. Reconcile. The returned list has matches: true, so the hook sets state to true and React re-renders.
4. Subscribe. The effect adds handleChange to that list's change event.
5. Preference changes. The browser emits { matches: false }; the handler stores false, and the consumer re-renders again.
6. Unmount. Cleanup removes handleChange from the original list. Later events cannot update the abandoned hook.

Complexity

Mount, cleanup, and each preference change take O(1) time. Each mounted hook instance stores O(1) state and owns one listener.

Gotchas

• Treating no-preference as another query. The contract asks whether reduce matches, so false already represents no request to reduce motion. Fix: use the exact reduce query and return its boolean.
• Using the default after the browser is available. A hydration-safe fallback is not a permanent override. Fix: copy mediaQuery.matches into state after mount.
• Attaching to window. The change event belongs to the returned MediaQueryList. Fix: subscribe and unsubscribe on that object.
• Removing a new arrow function. A different function reference does not remove the listener you added. Fix: name one handler inside the effect and reuse it in cleanup.
• Changing the document. A reporting hook should not toggle classes or disable animations itself. Fix: let consuming components decide how to respond to the boolean.

Going further

• Reusable query hook. Extract useMediaQuery(query, defaultValue) and define reduced motion by passing this exact query.
• Shared external store. Use useSyncExternalStore when many consumers should share one subscription and need concurrent-render snapshot semantics.
• Animation policy. Build a separate layer that replaces large motion with fades or instant transitions while preserving meaningful progress and loading feedback.