Reach UI Dialog: Adopt New Focus Defaults or Preserve Legacy Focus Behavior?

Adopt the new focus defaults unless you need to override them

Answer: Keep trapFocus={true} and returnFocusOnDismiss={true} (the v2 defaults) for most cases.

Confirmed facts

• Reach UI Dialog v2 (released with v0.13+) sets trapFocus and returnFocusOnDismiss to true by default.
• This behavior matches WAI‑ARIA modal requirements: focus is moved into the dialog when opened and returned to the triggering element when closed.
• If you are on a pre‑0.13 version, the dialog did not manage focus automatically.

Steps to verify and apply

1. Check your installed Reach UI version (npm list @reach/ui or similar).
2. If the version is ≥0.13, leave the props unset (or explicitly set them to true for clarity).
3. Test keyboard navigation: open the dialog via Tab or a button, press Escape or the close button, and confirm focus returns to the element that launched the dialog.
4. Run a screen‑reader check (NVDA, VoiceOver) to ensure the dialog title is announced and focus never escapes while the dialog is open.
5. If you discover custom focus‑restoration code that runs after the dialog closes, decide whether to keep it or let the dialog handle return focus. In that case, you may need to set returnFocusOnDismiss={false} and manage focus yourself.

When to consider preserving legacy behavior

Only if you have a specific requirement that conflicts with the default trap‑focus or return‑focus logic (e.g., a non‑modal popover that should not trap focus, or a custom focus‑restoration routine that would be duplicated). In those rare cases, explicitly set trapFocus={false} and/or returnFocusOnDismiss={false} and implement your own focus management while still testing for WCAG 2.1 AA compliance.