The State Reducer Pattern

The plain-language idea

The state reducer pattern is a way of writing a custom hook or component so that the person using it can override how state transitions happen, not just what the current values are. Instead of hard-coding the logic that decides what an action does, the hook accepts a reducer from its caller and runs that instead of (or wrapped around) its own default.

This is a different problem than useReducer itself solves. useReducer is the mechanism — a hook that runs (state, action) => newState internally, inside one component. The state reducer pattern is one level up: it's a design choice made by whoever authors a reusable hook, to expose that internal reducer as a customization point for whoever consumes it. You already know how to write a reducer; this lesson is about handing that pen to someone else.

See it in a real thing: a toggle that limits itself, without forking the hook

Start with an ordinary useToggle hook, built on useReducer like the earlier lesson:

function toggleReducer(state, action) {
  switch (action.type) {
    case "toggle":
      return { on: !state.on, clicks: state.clicks + 1 };
    case "reset":
      return { on: false, clicks: 0 };
    default:
      throw new Error(`Unhandled action: ${action.type}`);
  }
}

function useToggle({ reducer = toggleReducer } = {}) {
  const [state, dispatch] = useReducer(reducer, { on: false, clicks: 0 });
  const toggle = () => dispatch({ type: "toggle" });
  const reset = () => dispatch({ type: "reset" });
  return { ...state, toggle, reset };
}

The only thing that makes this the state reducer pattern is one line: reducer = toggleReducer is a parameter, not a hard-coded internal. Now a consumer who wants "stop toggling after 4 clicks" doesn't need to fork useToggle or ask its author to add a maxClicks prop — they write their own reducer that wraps the default:

function MaxFourToggle() {
  function stateReducer(state, action) {
    const next = toggleReducer(state, action); // run the real logic first
    if (action.type === "toggle" && state.clicks >= 4) {
      return { ...next, on: state.on }; // still counts the click, blocks the flip
    }
    return next;
  }

  const { on, clicks, toggle } = useToggle({ reducer: stateReducer });
  return (
    <button onClick={toggle}>
      {on ? "on" : "off"} ({clicks} clicks)
    </button>
  );
}

stateReducer calls toggleReducer first, then adjusts the result. This is the pattern's key move: the consumer intercepts a transition instead of replacing the whole state machine, so useToggle's author never had to anticipate "someone will eventually want a click limit."

What people usually miss

Watch out

• This is not the same thing as just adding more props. A hook could add a maxClicks prop instead, but that only covers the cases its author thought of. A state reducer covers cases nobody anticipated, because the consumer controls the actual transition logic, not a pre-built option.
• The consumer's reducer usually should call the default reducer, not replace it. Reimplementing the whole switch statement duplicates logic and drifts out of sync when the hook's author changes the default. Composing (as stateReducer does above) keeps one source of truth.
• This pattern shows up constantly in library code you already use — Downshift (the combobox/autocomplete library) popularized it under this exact name, and it's why some component libraries expose a stateReducer prop instead of a dozen individual behavior flags.

The genealogy: one level of indirection above useReducer

useReducer gives one component a clean way to express "what happened" as a plain action and let one function decide the consequence. The state reducer pattern takes that same (state, action) => newState shape and turns it into a public extension point — the hook's author writes the default transition logic, but hands the actual decision to whoever calls the hook. It's the same idea from the reducer lesson, just moved from "internal implementation detail" to "part of the API."