November 12, 2026
Accessible modal dialog: the W3C pattern, step by step
An accessible modal dialog is a window laid over the page, whose underlying content becomes inert, and which remains usable with a keyboard as well as with assistive technology. The W3C ARIA Authoring Practices Guide (APG) spells out how it should behave: when it opens, focus moves inside it; Tab and Shift + Tab cannot leave it; Escape closes it; when it closes, focus goes back to the element that opened it. In the markup, the container carries the dialog role, aria-modal="true" and an accessible name. This guide walks through each of these recommendations, including the nuances the W3C adds about where to put focus and when to use aria-modal, and ends with a code example you can adapt.
What is an accessible modal dialog according to the W3C?
The APG defines a dialog as a window overlaid on either the primary window or another dialog window. What makes it modal is that the windows under it are inert: users cannot interact with content outside the active dialog.
That inert content is typically visually obscured or dimmed so it is hard to discern. In some implementations, any attempt to interact with it closes the dialog.
Like non-modal dialogs, modal dialogs contain their own tab sequence. However, unlike most non-modal dialogs, a modal dialog provides no way to move keyboard focus outside the window without closing it. For a brief, important message meant to divert the user's attention, the W3C defines a special case, the alertdialog role, covered in a separate pattern: the Alert Dialog Pattern.
Initial focus: where should it go when the modal opens?
The baseline: when a dialog opens, focus moves to an element contained in the dialog. Generally, that is the first focusable element. But the APG notes that the most appropriate placement depends on the nature and size of the content, and lists several cases:
- Structured content (lists, tables, several paragraphs) that would be hard to understand if announced as one unbroken string: it is advisable to add tabindex="-1" to a static element at the start of the content and focus it first. This makes it easier for assistive technology users to read the content by navigating its structures. In this case, it is also advisable to omit aria-describedby on the container.
- Long content, where focusing the first interactive element could scroll the beginning out of view: it is advisable to add tabindex="-1" to a static element at the top of the dialog, such as the title or first paragraph, and focus it.
- Final step of a process that is not easily reversible (deleting data, completing a financial transaction): it may be advisable to put focus on the least destructive action. The Alert Dialog Pattern is often used in this situation.
- A dialog limited to giving information or continuing a process: it may be advisable to focus the element likely to be used most often, such as an OK or Continue button.
Focus trap in the modal: Tab, Shift + Tab and Escape
The APG calls a "tabbable element" any element with a tabindex value of zero or greater, and notes that values greater than 0 are strongly discouraged. Once the dialog is open, the keyboard should behave as follows:
- Tab: moves focus to the next tabbable element inside the dialog. From the last one, focus wraps to the first.
- Shift + Tab: moves focus to the previous tabbable element inside the dialog. From the first one, focus goes to the last.
- Escape: closes the dialog.
<button type="button" id="open-dialog">Delete account</button>
<div id="dialog" role="dialog" aria-modal="true"
aria-labelledby="dialog-title" aria-describedby="dialog-desc" hidden>
<h2 id="dialog-title">Delete this account?</h2>
<p id="dialog-desc">This action is permanent.</p>
<button type="button" id="cancel">Cancel</button>
<button type="button" id="confirm">Delete</button>
</div>
<script>
const dialog = document.getElementById('dialog');
const cancel = document.getElementById('cancel');
let opener = null;
function tabbables() {
return [...dialog.querySelectorAll('a[href], button, input, select, textarea, [tabindex]')]
.filter(el => !el.disabled && el.tabIndex >= 0);
}
function openDialog(event) {
opener = event.currentTarget; // remember the invoking element
dialog.hidden = false;
// To keep aria-modal="true", the rest of the page must become
// inert for all users AND be visually obscured (not shown here).
cancel.focus(); // least destructive action
}
function closeDialog() {
dialog.hidden = true;
if (opener && opener.isConnected) opener.focus(); // return focus
else document.querySelector('main h1')?.focus(); // fallback: a logical element (adapt; add tabindex="-1" if needed)
}
dialog.addEventListener('keydown', (e) => {
if (e.key === 'Escape') { closeDialog(); return; }
if (e.key !== 'Tab') return;
const items = tabbables();
const first = items[0], last = items[items.length - 1];
if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
});
document.getElementById('open-dialog').addEventListener('click', openDialog);
cancel.addEventListener('click', closeDialog);
</script>Closing the modal: where should focus return?
When the dialog closes, focus returns to the element that invoked it. The APG allows two exceptions. First, the invoking element no longer exists; focus then goes to another element that provides a logical work flow. Second, the work flow design includes conditions that can occasionally make focusing a different element a more logical choice: when users are very unlikely to need to re-invoke the dialog right away, and when the task completed in the dialog is directly related to a subsequent step.
The W3C's example: a grid has a toolbar with a button for adding rows. That Add Rows button opens a dialog asking for the number of rows. After the dialog closes, focus is placed in the first cell of the first new row.
Finally, it is strongly recommended that the tab sequence of every dialog include a visible element with role button that closes the dialog, such as a close icon or a Cancel button.
ARIA roles and attributes for an accessible modal dialog
The W3C pattern sets out the following roles, states and properties:
- The dialog container has the role dialog.
- All elements required to operate the dialog are descendants of the element with role dialog.
- The container has aria-modal set to true.
- The dialog has either an aria-labelledby value that refers to a visible dialog title, or a label specified with aria-label.
- Optional: aria-describedby, set on the element with role dialog, points to the element or elements describing the dialog's primary purpose or message. Screen readers can then announce that description along with the title and the initially focused element. This is typically helpful only when the description is simple and understandable without structural information; it is advisable to omit it if the content includes semantic structures such as lists, tables or several paragraphs that would be hard to follow read as one block.
aria-modal or aria-hidden: the W3C's cautions
Marking a dialog modal with aria-modal="true" can prevent users of some assistive technologies from perceiving content outside it. If a dialog is marked modal but does not behave as a modal for other users, the users of those assistive technologies face severe negative consequences. The APG therefore says to mark a dialog modal only when both conditions hold: application code prevents all users from interacting in any way with the outside content, and visual styling obscures that content.
The aria-modal property, introduced in ARIA 1.1, replaces aria-hidden for telling assistive technologies that content outside a dialog is inert. In legacy implementations that still rely on aria-hidden for this, two points matter:
- aria-hidden is set to true on each element containing a portion of the inert layer;
- the dialog element is not a descendant of any element that has aria-hidden set to true.
Checklist for testing your accessible modal dialog
To review an existing modal, go through the W3C pattern point by point, with the keyboard alone and then with a screen reader. The W3C also offers two reference examples: a modal dialog example showing multiple layers of dialogs with small and large amounts of content, and a date picker dialog with a calendar grid.
- On opening, is focus inside the dialog, at a spot suited to the content?
- Do Tab and Shift + Tab wrap without ever leaving the dialog?
- Does Escape close the dialog?
- On closing, does focus return to the invoking element or, if the invoking element no longer exists, to another logical element?
- Is a visible close button part of the tab sequence?
- Does the container have role="dialog", aria-modal="true" and a name via aria-labelledby or aria-label?
- Is the outside content truly inert for everyone and visually obscured?
Frequently asked questions
How do you make a modal dialog accessible?
Following the W3C, move focus into the dialog when it opens, make Tab and Shift + Tab wrap inside it, close it with Escape and return focus to the invoking element when it closes. The container carries role="dialog", aria-modal="true" and an accessible name via aria-labelledby or aria-label.
What ARIA role should a modal use?
The dialog role on the container. For a dialog that diverts the user's attention to a brief, important message, the W3C defines the alertdialog role, described in the Alert Dialog Pattern.
Where should focus go when a modal opens?
Generally on the first focusable element. If the content is structured or long, it is advisable to focus a static element with tabindex="-1", at the start of the content or at the top of the dialog (title, first paragraph). Before an action that is hard to reverse, it may be advisable to focus the least destructive action.
Should the Escape key close a modal?
Yes. In the W3C modal dialog pattern, Escape closes the dialog. It is also strongly recommended to include a visible close button in the tab sequence.
Should I use aria-modal or aria-hidden?
aria-modal, introduced in ARIA 1.1, replaces aria-hidden for signalling that outside content is inert. Mark a dialog modal only when code prevents all users from interacting with outside content and visual styling obscures it. In legacy implementations using aria-hidden, set aria-hidden="true" on each element of the inert layer and make sure the dialog is not a descendant of any element with aria-hidden="true".
Where does focus go when a modal closes?
To the element that opened it. If that element no longer exists, focus goes to another element that provides a logical work flow. If the work flow justifies it (users very unlikely to need to re-open it immediately, task directly tied to the next step), a different element may also be more relevant.
Further reading on Conformly
Sources
This article relies on the official sources listed at the end of the page.