Headless UI Pattern — React Deep Dive

what is "headless"? logic vs rendering

A headless component owns the plumbing — state, keyboard handling, ARIA wiring, focus management — but never renders a single <div>. The consumer owns the DOM. Two halves connect them: a state reducer (override any transition) and prop getters (spread the right props onto the right element). Invented by Kent C. Dodds, now powering react-table, downshift, Radix UI, Headless UI.

half	who owns it	what it gives the consumer
`state reducer`	consumer passes a custom `(state, action) → newState`	control over EVERY state transition — intercept, block, or rewrite changes
`prop getters`	component exposes `getXxxProps(extra)` helpers	spread the right a11y + event props without knowing internals
`render`	consumer writes the JSX, picks tags & classes	100% styling freedom — Tailwind, CSS-in-JS, plain CSS, anything
`plumbing`	component keeps it (a11y, keyboard, focus, IDs)	correctness the consumer doesn't have to think about

1 · the headless useToggle hook (edit me)

// useToggle is a HEADLESS hook: it owns state + the reducer contract + the
// prop getter, but never renders. The consumer controls behavior (via the
// reducer arg) and appearance (via the returned JSX).
function useToggle(reducer) {
  // The component's reducer defers to the consumer's reducer if provided.
  // Default contract: accept the proposed `changes` object as the new state.
  var innerReducer = React.useCallback(function (state, action) {
    if (reducer) {
      return reducer(state, action);
    }
    return action.changes;
  }, [reducer]);

  var statePair = React.useReducer(innerReducer, { isOpen: false });
  var innerState = statePair[0];
  var dispatch = statePair[1];

  // toggle dispatches the proposed next state. The reducer may accept or veto it.
  var toggle = React.useCallback(function () {
    dispatch({ type: 'TOGGLE', changes: { isOpen: !innerState.isOpen } });
  }, [innerState.isOpen]);

  // PROP GETTER: bundle the right a11y + event props, let the consumer override.
  // Object.assign(baseProps, extra) → consumer's `extra` always wins.
  var getToggleButtonProps = React.useCallback(function (extra) {
    return Object.assign({
      'data-testid': 'toggle-btn',
      type: 'button',
      'aria-expanded': innerState.isOpen,
      'aria-pressed': innerState.isOpen,
      onClick: toggle,
      className: 'px-4 py-2 rounded font-bold text-sm ' +
        (innerState.isOpen ? 'bg-[#61dafb] text-[#0d1117]' : 'bg-[#30363d] text-[#e6edf3]')
    }, extra || {});
  }, [innerState.isOpen, toggle]);

  return {
    isOpen: innerState.isOpen,
    toggle: toggle,
    getToggleButtonProps: getToggleButtonProps
  };
}

function HeadlessDemo() {
  // (1) Default behavior — no custom reducer, accept every change.
  var toggle1 = useToggle(null);

  // (2) Custom reducer — the consumer overrides transitions. Here: after the
  //     button has been OPENED 3 times, the reducer vetoes the next close.
  var opensCount = React.useRef(0);
  var lockReducer = React.useCallback(function (state, action) {
    if (action.type === 'TOGGLE') {
      // count an "open" when transitioning closed → open
      if (!state.isOpen && action.changes.isOpen) {
        opensCount.current = opensCount.current + 1;
      }
      // after 3 opens, block every close: keep it open forever
      if (!action.changes.isOpen && opensCount.current >= 3) {
        return state; // VETO — return current state, ignore proposed changes
      }
    }
    return action.changes; // default: accept
  }, []);
  var toggle2 = useToggle(lockReducer);

  return (
    <div className="max-w-sm mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-lg font-bold text-[#61dafb] mb-3">Headless UI Pattern</h2>

      {/* DEFAULT: spread the prop getter, render whatever we want */}
      <div className="mb-4 p-3 bg-[#0d1117] rounded border border-[#30363d]">
        <p className="text-xs text-[#8b949e] mb-2">Default toggle (no custom reducer):</p>
        <button {...toggle1.getToggleButtonProps({})}>
          {toggle1.isOpen ? 'OPEN' : 'CLOSED'}
        </button>
        <p data-testid="state-1" className="mt-2 text-xs text-[#8b949e]">
          State: {toggle1.isOpen ? 'open' : 'closed'}
        </p>
      </div>

      {/* CUSTOM REDUCER: same hook, consumer-steered behavior */}
      <div className="p-3 bg-[#0d1117] rounded border border-[#30363d]">
        <p className="text-xs text-[#8b949e] mb-2">Custom reducer (locks open after 3 opens):</p>
        <button {...toggle2.getToggleButtonProps({ 'data-testid': 'toggle-btn-2' })}>
          {toggle2.isOpen ? 'OPEN' : 'CLOSED'}
        </button>
        <p data-testid="state-2" className="mt-2 text-xs text-[#8b949e]">
          State: {toggle2.isOpen ? 'open' : 'closed'} · opens: {opensCount.current}
        </p>
      </div>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<HeadlessDemo />);

2 · Babel compiles JSX → element tree

The JSX spread {'{...getToggleButtonProps({})}'} becomes a _extends(...) call merging props into React.createElement. Clicking dispatches {'{type:"TOGGLE", changes:{isOpen:...}}'} — the consumer reducer decides whether those changes survive.

// (hit "compile & render" to see Babel's output)

3 · live React (the pattern, proven)

The gold-check clicks the default toggle twice (closed → open → closed) and asserts the state text after each click. That proves the prop-getter spread pipeline and the default state reducer work through real DOM events. Try the bottom button yourself: open it 3 times and watch the custom reducer veto the close.

state-1: — · gold: click toggle-btn → expect closed→open→closed

prop getter convention

intent	pattern	why
render the trigger	`<button {...getToggleButtonProps()}>`	gets aria-expanded, onClick, type=button, role in one spread
render the listbox/menu	`<ul {...getMenuProps()}>`	gets role=listbox, aria-labelledby, keyboard handler
render an option	`<li {...getItemProps({item, index})}>`	gets role=option, aria-selected, id, onClick, onMouseDown
override a prop	`getXxxProps({ className: 'mine', onClick: fn })`	extra props win via Object.assign — consumer styling/behavior composes
veto a transition	`if (...) return state;` in custom reducer	return current state to ignore proposed changes
rewrite a transition	`return { ...action.changes, extra: true }`	return a modified changes object — full control of next state