Focus Trap vs Native Restoration in Jira Align Modals

Direct Answer

Adding a focus‑trap to every Jira Align modal guarantees that keyboard‑only users stay inside the dialog until it is closed. For modals built with the Atlassian UI library, the trapFocus prop can be set to true and the library will automatically restore focus to the trigger element on close. For custom modals, you must implement aria-modal="true", set focus to the first focusable child on open, and explicitly call triggerElement.focus() in the onClose handler.

Why the Native Approach May Fail

The browser’s native focus restoration only works reliably when the element that opened the modal remains in the DOM and is focusable. In Jira Align, content is often injected via asynchronous calls or the opener is removed during a page refresh, causing the native restoration to lose focus or leave the user stranded outside the modal. This violates WCAG 2.1 AA (1.3.1) and can break screen‑reader announcements.

Performance & Customization Considerations

• Performance: The focus‑trap logic is lightweight (a few event listeners) and adds negligible overhead to page load or modal render time.
• Customization: Existing customizations that rely on manual focus handling may conflict with an automatic trap. Ensure that any custom onClose logic calls focus() after the trap is disabled.
• Browser Compatibility: All modern browsers support the necessary APIs (focus(), focusin event). Older browsers (IE11) may require polyfills if your environment still supports them.

When Native Restoration Is Sufficient

If you can guarantee that the trigger element stays in the DOM, remains focusable, and that the modal content is static, native restoration can suffice. However, for dynamic content scenarios (e.g., single‑page navigation, API‑driven UI updates) the risk of focus loss is high, so a focus‑trap is recommended.

Implementation Checklist

1. Identify whether the modal uses the Atlassian Modal component or a custom implementation.
2. If Atlassian: set trapFocus={true} and rely on the library’s onClose to restore focus.
3. If custom: add aria-modal="true", focus the first focusable element on open, and in the onClose handler call triggerElement.focus() after disabling the trap.
4. Verify that the trigger element is focusable (button, link, or tabindex="0").
5. Test with a screen reader and keyboard navigation to confirm focus cycles correctly.

Diagnostic Detail Needed

To finalize the recommendation, could you confirm whether all Jira Align modals in your environment are instantiated via the Atlassian UI library or if there are custom modal implementations?