Reach UI FocusScope vs Custom Focus Traps for Non-Linear Navigation

Answer

1. FocusScope does not provide a declarative way to alter the tab order. It traps focus inside its subtree and preserves the natural DOM sequence. 2. Use a custom focus trap only when the design requires a navigation order that cannot be expressed by the DOM. For most modal dialogs the convenience of FocusScope outweighs the overhead of a custom implementation. 3. When dynamic focusable elements or conditional skipping are involved, a small imperative wrapper around FocusScope is usually sufficient; full custom traps are reserved for very complex patterns.

Explanation

FocusScope automatically adds tabindex=-1 to elements outside the subtree and restores focus to the first focusable child when the component mounts. The navigation sequence it enforces follows the DOM order; it does not expose props or callbacks to reorder or skip elements. Therefore, if a modal requires that pressing Tab jump from a button to a distant panel, the only way to achieve that with FocusScope is to add imperative logic (e.g., keydown listeners that call focus() on a custom element).

Building a custom trap means you must manage a list of focusable elements, handle Tab and Shift+Tab, and ensure focus never leaks to the background. This adds code complexity and maintenance risk, especially when elements are added or removed dynamically.

In practice, the trade‑off is simple: if the DOM order already matches the desired navigation flow, stick with FocusScope. If you need to skip, reorder, or conditionally focus elements, wrap FocusScope in a lightweight manager that listens for key events and calls focus() on the next element in a custom list. Only when the pattern is very complex (e.g., multiple nested portals, conditional focus based on user state) should you consider a full custom trap implementation.

Practical Steps for Your Project

1. Assess the DOM order. Render the modal and tab through the elements. If the order matches the desired experience, you can use <FocusScope> as-is.
2. Identify non‑linear requirements. List any elements that must be skipped or visited out of DOM order.
3. Implement a lightweight manager. Wrap <FocusScope> in a component that:
   • Registers a keydown listener for Tab and Shift+Tab.
   • Maintains an array of refs or selectors representing the desired focus sequence.
   • On key events, calculates the next element and calls focus().
4. Test for leaks. Use a keyboard‑only navigation test and run an axe‑core audit to confirm focus never escapes the modal.
5. Iterate. If new dynamic elements appear, update the focus list or enhance the manager to query the DOM at runtime.

When Custom Traps Become Justified

If the modal contains:

• Multiple independent focus zones that must be navigated in a specific order.
• Conditional focus jumps based on user actions (e.g., a step‑by‑step wizard).
• Dynamic addition or removal of focusable elements that cannot be represented statically in the DOM.

In such cases, a dedicated custom trap library (e.g., focus-trap-react) or a hand‑rolled implementation is preferable.

Missing Diagnostic Detail

Do any of your modal overlays add or remove focusable elements at runtime (e.g., via user input, API responses, or conditional rendering)? If so, that may influence whether a custom trap is necessary.