Focus management: focus is application state you own

Route changes move focus nowhere

On a full page load the browser does three accessibility jobs for free: it resets focus to the top of the new document, announces the document title, and starts the reading order from a known place. A client-side route change does none of them. React swaps a subtree; focus either stays on whatever survived the diff (a nav link far from the new content) or — if the previously focused element unmounted — falls back to body, the screen reader says nothing, and the user’s next Tab starts from wherever the corpse was buried. The standard remedy is to treat navigation as a focus event: after the new view commits, focus its h1 given tabIndex={-1}, and update document.title. The -1 matters — it makes the heading programmatically focusable without inserting it into the Tab order, so keyboard users are not forced to stop on a non-interactive element forever after. Focusing the heading does double duty: the screen reader announces it (context: “Payment details, heading level 1”), and sequential focus now continues from the top of the new content instead of the old DOM position.

function RouteHeading({ children }) {
  const ref = useRef(null);
  useEffect(() => {
    // on mount of a new route view: announce + reposition focus
    ref.current?.focus();
  }, []);
  return <h1 tabIndex={-1} ref={ref}>{children}</h1>;
}

The alternative is a live-region route announcer (an aria-live="polite" element whose text you set to the new page name) — it announces without moving focus, which suits cases where moving focus would be disruptive, but it does not fix the “next Tab starts from nowhere” half of the problem. Production routers and frameworks ship variants of both; the part that stays your responsibility is choosing the focus target per navigation type — a wizard step wants the heading, an in-page filter update usually wants focus left alone plus a polite announcement of the result count.

The dialog focus contract

A modal dialog is a focus contract with four clauses, and APG spells them out. On open: move focus inside — to the first sensible focusable, or to the dialog container itself for confirmation dialogs where focusing the “Delete forever” button would be a loaded gun. While open: focus is trapped — Tab from the last element wraps to the first, and the page behind is inert; the modern mechanism is the inert attribute on the background container (or the native dialog element’s showModal(), which provides top-layer rendering, Escape, and background inertness in one move). inert is the important half that hand-rolled traps forget: a Tab-key trap stops the keyboard, but without inertness a screen reader’s virtual cursor walks straight out of the dialog into the background page. On Escape: close. On close: return focus to the element that opened the dialog — store a reference to document.activeElement before you move focus, and restore it after unmount.

Restoration is the clause teams break most, and it composes badly with the other clauses: a trap without restoration means every dialog interaction ends with the user dumped at body — the trap made the dialog usable and the missing restore made closing it a cliff. The senior-grade edge case: the trigger may not exist anymore when the dialog closes (the dialog’s job was to delete the row containing the trigger). Restoration therefore needs a fallback chain — trigger if alive, else the nearest surviving container or the list heading — which is precisely the “focus is application state” claim made concrete: you are computing the next focus position from your data model, not from the DOM.

Races, deletions, and the two focus pseudo-classes

Focus can only land on a node that exists. The classic React race: an event handler calls setShowPanel(true) and then panelRef.current.focus() — but state updates are batched and asynchronous, the panel has not rendered yet, panelRef.current is null, and focus silently goes nowhere. flushSync from react-dom exists for exactly this: wrap the state update in flushSync(() => setShowPanel(true)), and React commits the DOM synchronously before the next line, so the focus() call finds the node. It is a deliberate escape hatch with a real cost — a synchronous render of the affected subtree, bypassing batching — so the rule is: flushSync for focus (and scroll, and selection) positioning after a state-driven mount, and nothing else.

Deletion is the same theorem from the other side: when the focused element unmounts, the browser moves focus to body — there is no “nearest sibling” heuristic in the platform. So compute the successor before mutating: focus the next row’s equivalent control, else the previous row’s, else the list heading with tabIndex={-1}. Your data model knows the neighbor; the DOM after deletion does not.

Two adjacent distinctions complete the toolkit. :focus matches whenever the element has focus; :focus-visible matches when the browser heuristics say an indicator should be shown — keyboard interaction yes, mouse click usually no. The modern pattern is a strong ring on :focus-visible instead of deleting outlines (the ancient outline: none crime was motivated by mouse-click rings; :focus-visible removes the motivation). And scrollIntoView is not focus: it moves pixels, not the sequential-focus position — after scrolling an element into view, the user’s next Tab still continues from the old location. If the user should interact from the new place, you focus; if they should merely see it, you scroll; doing one while meaning the other is a category error that only keyboard users experience.