Modal

A modal dialog overlays the page to present content or request a decision, blocking interaction with the rest of the interface until it is dismissed.

Demo

Click the "Open Modal" button to launch the dialog. While the modal is open, try pressing Tab to cycle through focusable elements and Escape to close it. Confirm that focus returns to the trigger button after the modal closes.

What to Observe

Focus moves into the modal immediately when it opens, landing on the first focusable element.
Tab and Shift+Tab cycle only through elements inside the modal — focus cannot escape to the page behind it.
Pressing Escape closes the modal and returns focus to the element that triggered it.
Screen readers announce the dialog role and its accessible name when it opens.
The content behind the modal is inert — it cannot be clicked, scrolled, or reached by keyboard while the dialog is open.

Anatomy

[Anatomy image placeholder — will be added when assets are available]

Backdrop / overlay: The dimmed layer covering the page that signals the modal is active and prevents interaction with background content.
Dialog container: The panel that holds all modal content, marked up with the dialog role and an accessible name.
Dialog title: The heading inside the dialog that names the purpose of the modal, used as its accessible label.
Body content: The main message, form, or information displayed within the dialog.
Action buttons: Buttons that confirm, cancel, or otherwise resolve the modal's purpose.
Close button: An explicit control, typically in the header area, that dismisses the modal.

Accessibility Behavior

The dialog element must have an accessible name, typically derived from its visible title.
When the modal opens, focus must move inside it automatically — do not leave focus on the trigger or on the document body.
Focus must be trapped within the modal while it is open; Tab and Shift+Tab must not allow focus to reach elements behind the overlay.
Pressing Escape must close the modal and return focus to the element that originally opened it.
Background content must be hidden from assistive technologies while the modal is open.
All interactive controls inside the modal must be reachable and operable by keyboard.

Common Mistakes

Not trapping focus inside the modal, allowing keyboard users to Tab into hidden background content.
Failing to return focus to the trigger when the modal closes, leaving keyboard users at the top of the page.
Using a div instead of a proper dialog element or not applying the correct role, so screen readers do not identify it as a dialog.
Omitting an accessible name on the dialog, so screen readers announce it without context.
Relying solely on clicking the backdrop to close the modal, with no keyboard-accessible dismissal path.

Why This Matters

Modals interrupt the normal page flow and demand a user's attention. When focus management is broken, keyboard and screen reader users can become disoriented — either stuck inside a dialog they cannot exit or dropped back at the top of the page after closing one. Proper focus trapping and restoration ensure that modals feel predictable and safe for everyone, preventing the frustration of losing one's place in a complex workflow.

Accessibility Validation

This component is validated against internal accessibility criteria aligned with WCAG standards, using our internally developed system, Resonance Specs.

To learn more, please contact us.