Building a Scalable Focus Registry for Complex React Navigation

Current Situation Analysis

Focus management in complex React applications remains one of the most fragile aspects of frontend architecture. When building multi-level navigation, dropdowns, or tabbed interfaces, developers frequently encounter a critical gap: individual focusable elements have no inherent knowledge of their siblings, parents, or the broader component tree. This isolation makes keyboard-driven traversal (arrow keys, Tab, Escape) notoriously difficult to implement reliably.

The problem is often overlooked because early-stage prototypes rely on document.querySelectorAll or direct DOM references. While functional in simple cases, these approaches fracture under React’s concurrent rendering model, server-side hydration, and dynamic list virtualization. WCAG 2.2 Success Criterion 2.1.1 (Keyboard) and 2.4.3 (Focus Order) mandate predictable, programmatic focus movement. Yet, industry audits consistently show that over 65% of enterprise React applications fail automated keyboard navigation checks due to brittle traversal logic and state desynchronization.

The root cause isn’t a lack of APIs—it’s architectural. Without a centralized registry that maps UI hierarchy to focusable nodes, every component reinvents traversal logic. This leads to duplicated code, race conditions during focus shifts, and inaccessible experiences for keyboard and assistive technology users.

WOW Moment: Key Findings

Replacing ad-hoc DOM queries with a reactive focus registry fundamentally changes how keyboard navigation scales. The table below compares three common architectural patterns for managing focus traversal in nested React components:

Approach	Traversal Speed	State Sync	SSR/Hydration Safe	Maintenance Overhead
Direct DOM Query	O(n) per keystroke	Manual/Event-driven	❌ Breaks on hydration	High (fragile selectors)
Prop Drilling + Callbacks	O(1)	Synchronous	✅	Very High (wrapper hell)
Context/Reducer Registry	O(1) lookup	Deterministic	✅	Low (centralized logic)

The registry pattern decouples focus logic from the render tree. Instead of components searching the DOM or passing callbacks through multiple layers of wrappers, every focusable node registers itself into a single source of truth. The reducer tracks parent-child relationships, open/closed states, and sibling arrays. This enables O(1) focus resolution, eliminates stale closure bugs, and guarantees that keyboard traversal remains consistent regardless of how deeply nested the UI becomes.

Core Solution

Building a scalable focus registry requires three architectural layers: a deterministic state container, a registration mechanism, and a consumption hook. We’ll implement this using React’s Context API, useReducer, and forward refs.

Step 1: Define the Registry Shape

Each node in the navigation tree needs to track its controlling element, its children, and its visibility state. The registry is an array of these nodes.

export interface FocusNode {
  id: string;
  parentRef: React.RefObject<HTMLElement | null>;
  children: React.RefObject<HTMLElement | null>[];
  isExpanded: boolean;
}

export interface FocusRegistryState {
  nodes: FocusNode[];
  activeNodeId: string | null;
}

Step 2: Build the Reducer

A reducer ensures state transitions are predictable. We need actions to register nodes, toggle expansion, and update the active focus target.

type RegistryAction =
  | { type: 'REGISTER_NODE'; payload: FocusNode }
  | { type: 'UNREGISTER_NODE'; payload: string }
  | { type: 'TOGGLE_EXPANSION'; payload: string }
  | { type: 'SET_ACTIVE'; payload: string };

function focusRegistryReducer(
  state: FocusRegistryState,
  action: RegistryAction
): FocusRegistryState {
  switch (action.type) {
    case 'REGISTER_NODE':
      if (state.nodes.some(n => n.id === action.payload.id)) return state;
      return { ...state, nodes: [...state.nodes, action.payload] };
    case 'UNREGISTER_NODE':
      return { ...state, nodes: state.nodes.filter(n => n.id !== action.payload) };
    case 'TOGGLE_EXPANSION':
      return {
        ...state,
        nodes: state.nodes.map(n =>
          n.id === action.payload ? { ...n, isExpanded: !n.isExpanded } : n
        ),
      };
    case 'SET_ACTIVE':
      return { ...state, activeNodeId: action.payload };
    default:
      return state;
  }
}

Step 3: Create the Provider

The provider wraps the navigation tree and exposes registration and traversal utilities. We use useCallback to memoize functions and prevent unnecessary re-renders in consuming components.

import { createContext, useContext, useReducer, useCallback } from 'react';

const FocusRegistryContext = createContext<{
  state: FocusRegistryState;
  registerNode: (node: FocusNode) => void;
  unregisterNode: (id: string) => void;
  toggleNode: (id: string) => void;
  setActiveNode: (id: string) => void;
  findSibling: (currentId: string, direction: 'next' | 'prev') => React.RefObject<HTMLElement | null> | null;
} | null>(null);

export function FocusRegistryProvider({ children }: { children: React.ReactNode }) {
  const [state, dispatch] = useReducer(focusRegistryReducer, {
    nodes: [],
    activeNodeId: null,
  });

  const registerNode = useCallback((node: FocusNode) => {
    dispatch({ type: 'REGISTER_NODE', payload: node });
  }, []);

  const unregisterNode = useCallback((id: string) => {
    dispatch({ type: 'UNREGISTER_NODE', payload: id });
  }, []);

  const toggleNode = useCallback((id: string) => {
    dispatch({ type: 'TOGGLE_EXPANSION', payload: id });
  }, []);

  const setActiveNode = useCallback((id: string) => {
    dispatch({ type: 'SET_ACTIVE', payload: id });
  }, []);

  const findSibling = useCallback(
    (currentId: string, direction: 'next' | 'prev') => {
      const parentNode = state.nodes.find(n =>
        n.children.some(c => c.current?.id === currentId)
      );
      if (!parentNode) return null;

      const currentIndex = parentNode.children.findIndex(
        c => c.current?.id === currentId
      );
      const targetIndex = direction === 'next' ? currentIndex + 1 : currentIndex - 1;

      if (targetIndex >= 0 && targetIndex < parentNode.children.length) {
        return parentNode.children[targetIndex];
      }
      return null;
    },
    [state.nodes]
  );

  return (
    <FocusRegistryContext.Provider
      value={{ state, registerNode, unregisterNode, toggleNode, setActiveNode, findSibling }}
    >
      {children}
    </FocusRegistryContext.Provider>
  );
}

Step 4: Build the Consumption Hook

The hook abstracts context access and provides a clean API for components. It also includes a safety check for missing providers.

export function useFocusRegistry() {
  const context = useContext(FocusRegistryContext);
  if (!context) {
    throw new Error('useFocusRegistry must be used within a FocusRegistryProvider');
  }
  return context;
}

Step 5: Wire the Components

Focusable elements register themselves on mount and clean up on unmount. We use useEffect for registration and forward refs to maintain direct DOM access without triggering re-renders.

import { useRef, useEffect, forwardRef } from 'react';
import { useFocusRegistry } from './useFocusRegistry';

interface FocusableItemProps {
  id: string;
  children: React.ReactNode;
}

export const FocusableItem = forwardRef<HTMLButtonElement | HTMLAnchorElement, FocusableItemProps>(
  ({ id, children }, ref) => {
    const internalRef = useRef<HTMLElement>(null);
    const { registerNode, unregisterNode, state } = useFocusRegistry();

    useEffect(() => {
      const node: FocusNode = {
        id,
        parentRef: { current: null }, // Populated by parent container
        children: [],
        isExpanded: false,
      };
      registerNode(node);
      return () => {
        unregisterNode(id);
      };
    }, [id, registerNode, unregisterNode]);

    return (
      <button 
        ref={(el) => {
          if (typeof ref === 'function') ref(el);
          else if (ref) ref.current = el;
          internalRef.current = el;
        }} 
        aria-current={state.activeNodeId === id ? 'true' : undefined}
      >
        {children}
      </button>
    );
  }
);

Architecture Decisions and Rationale

• Why useReducer over useState? Focus traversal involves multiple interdependent updates (active node, expansion state, sibling lookup). A reducer centralizes logic, prevents race conditions, and makes state transitions auditable.
• Why refs over state for DOM elements? Storing DOM nodes in React state triggers re-renders. Refs provide direct access without affecting the render cycle, which is critical for performance during rapid keyboard input.
• Why context over prop drilling? Navigation trees often span 4-6 component layers. Context eliminates wrapper components and keeps focus logic decoupled from UI presentation.

Pitfall Guide

1. Stale Closures in Focus Callbacks Explanation: Event handlers capturing outdated state or refs will focus the wrong element or fail entirely. Fix: Always read refs directly inside event handlers. Use useCallback with explicit dependencies, or read from the latest state via a ref pattern (useLatest).

2. Bypassing React’s Lifecycle with Direct DOM Manipulation Explanation: Calling element.focus() on an unmounted or virtualized node throws errors or causes silent failures. Fix: Validate ref.current exists and is attached to the DOM before focusing. Use requestAnimationFrame to defer focus until after React commits updates.

3. Missing Cleanup on Unmount Explanation: Nodes remain in the registry after components unmount, causing memory leaks and incorrect sibling calculations. Fix: Implement a UNREGISTER_NODE action in the reducer. Call it in the useEffect cleanup function.

4. Assuming Synchronous Focus After State Update Explanation: React batches state updates. Calling focus() immediately after setActiveNode() may target a stale reference. Fix: Use useLayoutEffect or requestAnimationFrame to schedule focus after the DOM reflects the new state.

5. Desynchronizing aria-expanded from Internal State Explanation: Screen readers rely on aria-expanded to announce subtree visibility. If it doesn’t match the registry’s isExpanded flag, accessibility breaks. Fix: Derive aria-expanded directly from the registry state. Never hardcode it in JSX.

6. Ignoring Tab vs. Arrow Key Semantics Explanation: Tab moves between interactive regions; Arrow moves within a group. Mixing them confuses keyboard users. Fix: Implement roving tabindex for Tab navigation. Reserve Arrow keys for sibling traversal within the registered list.

7. Over-Engineering with State Machines Explanation: XState or similar libraries add complexity when a simple registry suffices. Fix: Start with a reducer-based registry. Only introduce state machines when focus logic requires complex conditional branching or history tracking.

Production Bundle

Action Checklist

• Define FocusNode and FocusRegistryState interfaces with strict typing
• Implement useReducer with explicit action types for registration, toggling, and focus updates
• Wrap the navigation tree with FocusRegistryProvider at the highest logical boundary
• Create useFocusRegistry hook with runtime provider validation
• Attach useEffect registration/cleanup to every focusable component
• Validate ref.current existence before calling .focus()
• Sync aria-expanded and aria-current attributes with registry state
• Test keyboard traversal with screen readers (NVDA/VoiceOver) and automated axe-core audits

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Flat navigation (< 5 items)	Roving tabindex + useState	Simpler implementation, lower bundle size	Low
Nested dropdowns/menus	Context/Reducer Registry	Predictable sibling traversal, avoids prop drilling	Medium
Dynamic/virtualized lists	Registry + Intersection Observer	Handles mount/unmount cycles gracefully	High
Multi-step wizard focus	State Machine (XState)	Complex conditional routing and history	Very High

Configuration Template

// focus-registry.ts
import { createContext, useContext, useReducer, useCallback, RefObject } from 'react';

export interface FocusNode {
  id: string;
  parentRef: RefObject<HTMLElement | null>;
  children: RefObject<HTMLElement | null>[];
  isExpanded: boolean;
}

export interface FocusRegistryState {
  nodes: FocusNode[];
  activeNodeId: string | null;
}

type RegistryAction =
  | { type: 'REGISTER_NODE'; payload: FocusNode }
  | { type: 'UNREGISTER_NODE'; payload: string }
  | { type: 'TOGGLE_EXPANSION'; payload: string }
  | { type: 'SET_ACTIVE'; payload: string };

function focusRegistryReducer(state: FocusRegistryState, action: RegistryAction): FocusRegistryState {
  switch (action.type) {
    case 'REGISTER_NODE':
      return { ...state, nodes: [...state.nodes, action.payload] };
    case 'UNREGISTER_NODE':
      return { ...state, nodes: state.nodes.filter(n => n.id !== action.payload) };
    case 'TOGGLE_EXPANSION':
      return { ...state, nodes: state.nodes.map(n => n.id === action.payload ? { ...n, isExpanded: !n.isExpanded } : n) };
    case 'SET_ACTIVE':
      return { ...state, activeNodeId: action.payload };
    default:
      return state;
  }
}

const FocusRegistryContext = createContext<{
  state: FocusRegistryState;
  registerNode: (node: FocusNode) => void;
  unregisterNode: (id: string) => void;
  toggleNode: (id: string) => void;
  setActiveNode: (id: string) => void;
} | null>(null);

export function FocusRegistryProvider({ children }: { children: React.ReactNode }) {
  const [state, dispatch] = useReducer(focusRegistryReducer, { nodes: [], activeNodeId: null });

  const registerNode = useCallback((node: FocusNode) => dispatch({ type: 'REGISTER_NODE', payload: node }), []);
  const unregisterNode = useCallback((id: string) => dispatch({ type: 'UNREGISTER_NODE', payload: id }), []);
  const toggleNode = useCallback((id: string) => dispatch({ type: 'TOGGLE_EXPANSION', payload: id }), []);
  const setActiveNode = useCallback((id: string) => dispatch({ type: 'SET_ACTIVE', payload: id }), []);

  return (
    <FocusRegistryContext.Provider value={{ state, registerNode, unregisterNode, toggleNode, setActiveNode }}>
      {children}
    </FocusRegistryContext.Provider>
  );
}

export function useFocusRegistry() {
  const ctx = useContext(FocusRegistryContext);
  if (!ctx) throw new Error('Missing FocusRegistryProvider');
  return ctx;
}

Quick Start Guide

1. Install dependencies: Ensure React 18+ or 19+ is configured. No external packages required.
2. Wrap your navigation: Import FocusRegistryProvider and wrap your top-level nav component.
3. Register items: In each focusable component, call registerNode in a useEffect with a unique id and ref.
4. Handle keyboard events: Use useFocusRegistry() to access findSibling or setActiveNode. Attach to onKeyDown.
5. Test traversal: Press Arrow keys to verify sibling movement. Press Tab to confirm roving tabindex behavior. Run axe-core to validate WCAG compliance.