# Accessible Modal Dialog: Focus, Escape and ARIA

Source: https://allyway.ai/glossary/accessible-modal-dialog

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](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (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](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) 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](https://allyway.ai/glossary/accessible-name) |

> **Note:** > **Kept inside is not a keyboard trap**
> Keeping Tab inside an open dialog is intended. It only becomes a [keyboard trap](https://allyway.ai/glossary/keyboard-trap) if users cannot leave it – which is why Escape and a visible close button matter.

## Examples

The native `dialog` element handles most of this for you when opened with `showModal()`:

```html title="Example"
<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](https://allyway.ai/glossary/aria) for the rule of preferring native HTML.

**Do:** Do

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.

**Don't:** Don't

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

Q: What makes a modal dialog accessible?
A: 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.

Q: Should I use the HTML dialog element or ARIA?
A: 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.

Q: Where should focus go when a dialog opens?
A: 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.

Q: Is trapping focus in a modal allowed?
A: 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.

Q: Which WCAG criteria apply to modal dialogs?
A: 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](https://allyway.ai/regulations/wcag-2-2).
