Free scan

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:

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:

<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:

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:

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.

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.