Accessible Modal Dialog: Focus, Escape and ARIA
Also called: Accessible modal, Accessible pop-up, Dialog window
Definition
An accessible modal dialog is a pop-up window that keyboard and screen reader users can use like everyone else: focus moves into it when it opens, the page behind it is inert, Escape closes it and focus returns to the control that opened it. Its focus handling falls under WCAG 2.4.3 Focus Order at Level A.
An accessible modal dialog is a pop-up – a login window, a newsletter prompt, a "quick view" in a shop – that works for people who don't use a mouse. Many dialogs open visually but leave the keyboard focus on the page behind them, so keyboard users tab through hidden links while the dialog waits on top, and screen reader users never learn it appeared. Getting the focus right is most of the work.
What it means
A modal dialog takes over the page until it is closed. W3C uses it as an example for WCAG 2.4.3 Focus Order (Level A): when the trigger button is activated, the dialog opens and focus is set within it; while it is open, content outside is inert and cannot receive focus; when it is dismissed, focus returns to the trigger button or the element after it. W3C lists the HTML dialog element as technique H102, and failure F85 describes dialogs that are not next to their trigger in the navigation order.
The WAI-ARIA Authoring Practices dialog (modal) pattern adds the expected keyboard behavior and markup:
| Part | Expected behavior |
|---|---|
| Opening | Focus moves to an element inside the dialog, usually the first focusable one |
| Tab / Shift+Tab | Focus cycles inside the dialog and wraps from last to first |
| Escape | Closes the dialog |
| Closing | Focus returns to the element that opened it |
role="dialog" |
On the container; alertdialog for brief, urgent messages |
aria-modal="true" |
Tells assistive technology the content behind is inert |
aria-labelledby |
Points to the visible dialog title, giving it an accessible name |
Examples
The native dialog element handles most of this for you when opened with showModal():
<button type="button" id="open">Sign up for our newsletter</button>
<dialog id="newsletter" aria-labelledby="nl-title">
<h2 id="nl-title">Newsletter</h2>
<form method="dialog">
<label for="nl-email">Email address</label>
<input id="nl-email" type="email" autocomplete="email">
<button value="ok">Subscribe</button>
<button value="cancel">Close</button>
</form>
</dialog>
<script>
const dialog = document.getElementById('newsletter');
const opener = document.getElementById('open');
opener.addEventListener('click', () => dialog.showModal());
dialog.addEventListener('close', () => opener.focus());
</script>showModal() makes the rest of the page inert, puts focus into the dialog and closes it on Escape. The close listener returns focus to the button, as W3C describes. If you build a dialog from a div, you need role="dialog", aria-modal="true", a focus loop and the Escape handling yourself – see ARIA for the rule of preferring native HTML.
Move focus into the dialog, give it a visible title linked with aria-labelledby, close it with Escape and a labeled close button, keep the page behind inert, and return focus to the trigger.
Open a dialog without moving focus, let Tab wander to the page behind it, use an icon-only close button without a name, open it automatically on page load, or leave focus at the top of the page after closing.
How to check an accessible modal dialog
Questions
What makes a modal dialog accessible?
Focus moves into it when it opens, the page behind is inert, Tab stays inside, Escape closes it, and focus returns to the trigger afterwards. It also needs a visible title that names it for screen readers.
Should I use the HTML dialog element or ARIA?
Prefer the native dialog element opened with showModal() – W3C lists it as technique H102 for WCAG 2.4.3. Build a custom div dialog with role="dialog" and aria-modal="true" only if you cannot use the native element.
Where should focus go when a dialog opens?
According to the WAI-ARIA Authoring Practices, usually to the first focusable element inside it. For long content, the title or the start of the content can be a better target, so users don't miss what comes first.
Is trapping focus in a modal allowed?
Yes, while the dialog is open. W3C's own example for 2.4.3 makes the content outside inert. It must be easy to leave, though: Escape and a labeled close button keep it from becoming a keyboard trap.
Which WCAG criteria apply to modal dialogs?
Mainly 2.4.3 Focus Order and 2.1.1 Keyboard, plus 4.1.2 Name, Role, Value for the dialog role and name, and 2.1.2 No Keyboard Trap. All are Level A in WCAG 2.2.
Related terms
Focus Order: Logical Tab Order Explained (WCAG 2.4.3)
Focus order is the sequence in which interactive elements receive keyboard focus when a user presses Tab. WCAG 2.4.3 requires that this sequence preserves the meaning and operability of the page.
Read definition: Focus Order: Logical Tab Order Explained (WCAG 2.4.3)Keyboard Trap: WCAG 2.1.2 Explained and Fixed
A keyboard trap is a part of a page that keyboard focus can enter but not leave using the keyboard alone. WCAG 2.1.2 No Keyboard Trap forbids it at Level A.
Read definition: Keyboard Trap: WCAG 2.1.2 Explained and FixedARIA: Roles, States and Properties Explained
ARIA (WAI-ARIA, Accessible Rich Internet Applications) is a W3C specification of HTML attributes – roles, states and properties – that tell assistive technology what a custom element is, what it is called and what state it is in.
Read definition: ARIA: Roles, States and Properties ExplainedAccessible Name: What It Is and How It Is Computed
The accessible name is the text that browsers pass to assistive technology to identify an element – for example the words a screen reader announces for a button, link or form field. WCAG 4.1.2 requires a programmatically determinable name for every user interface component.
Read definition: Accessible Name: What It Is and How It Is Computed