Modals & Dialogs

A modal dialog is an overlay that appears above the main page content and
requires the user to interact with it before returning to the page. When
implemented incorrectly, modal dialogs are among the most common and severe
accessibility failures — trapping keyboard users, disorientating screen reader
users, and making content unreachable.
[1]

---

Required behaviour

An accessible modal dialog must:

1. Move focus into the dialog when it opens — to the first focusable element or the dialog heading
2. Trap focus inside the dialog — Tab and Shift+Tab must cycle only within the dialog
3. Allow the dialog to be closed with Escape
4. Return focus to the triggering element when the dialog closes
5. Use role="dialog" and aria-modal="true"
6. Have an accessible name via aria-labelledby referencing the dialog heading

[2]

---

ARIA attributes

Attribute

Value

Purpose

role

dialog

Identifies the element as a dialog

aria-modal

true

Tells screen readers to ignore content behind the dialog

aria-labelledby

id of heading

Names the dialog

aria-describedby

id of description

Optional additional description

---

The aria-modal caveat

aria-modal="true" instructs screen readers to treat only the dialog content
as accessible, hiding everything behind it. However, support varies — some
screen readers ignore aria-modal. For robustness, also apply inert or
aria-hidden="true" to all elements outside the dialog when it is open.
[3]

The HTML inert attribute is now widely supported and is the most reliable
way to make background content unreachable:

• Apply inert to the page root or all siblings of the dialog container
• Remove inert when the dialog closes

---

Non-modal dialogs

Not all dialogs need to be modal. A non-modal dialog (role="dialog" without
focus trapping) allows users to interact with the page while the dialog is
open. Use this pattern for persistent panels or toolbars.

For non-modal dialogs, focus should still move into the dialog on open, and
Escape should still close it. Focus trapping is not required.
[2]

---

Common mistakes

No focus trap. Focus escaping the dialog into the page behind is the
most common modal failure. Keyboard users become lost in content they cannot see.

Focus not moved on open. If focus stays on the trigger when the dialog
opens, screen reader users will not know the dialog exists.

Focus not returned on close. Returning focus to the body or page top
forces keyboard users to navigate back to where they were.

Closing only with a button. Escape must always close the dialog. Some
dialogs also close on overlay click — if so, ensure this is keyboard operable too.

---

References

1. W3C Web Accessibility Initiative. Understanding Success Criterion 2.1.2: No Keyboard Trap. https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html ↑
2. W3C Web Accessibility Initiative. ARIA Authoring Practices Guide — Dialog (Modal) Pattern. https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ ↑
3. MDN Web Docs. The inert attribute. https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inert ↑