DEV Community

Denis Omerovic
Denis Omerovic

Posted on • Originally published at getaccessguard.com

Accessible Modals: How to Build Dialogs That Don't Trap, Confuse, or Exclude Users

#a11y #webdev #javascript #html

Modals are everywhere. Cookie consent, login forms, confirmation dialogs, image lightboxes, newsletter signups, settings panels. The average user hits a modal within seconds of landing on most commercial websites. And most of those modals are broken for anyone not using a mouse.

We scanned over 15,000 pages through AccessGuard last quarter. Modal dialogs appeared on roughly 40 percent of them. Of the pages with modals, over 70 percent failed at least one WCAG criterion directly because of the modal itself, not the page behind it. The three most common failures were missing focus management, no keyboard escape route, and screen readers not knowing the modal existed.

This post covers every accessibility requirement for modal dialogs, what the relevant WCAG criteria actually say, and the exact code patterns that satisfy each one.

Why modals are uniquely dangerous for accessibility

A modal dialog does something no other UI pattern does: it demands exclusive attention. It sits on top of everything, it (should) prevent interaction with the page behind it, and it expects the user to deal with it before doing anything else.

For sighted mouse users, that contract is visually obvious. The backdrop dims, the box appears in the center, you click inside it or click the X to close it.

For everyone else, the contract is invisible unless you build it explicitly. A screen reader user has no idea a modal just appeared unless you tell their assistive technology. A keyboard user cannot "see" the backdrop and will tab straight out of the modal into the page behind it unless you trap focus.

The WCAG criteria that apply to modals

Modals touch a surprisingly large number of WCAG success criteria. Here are the ones that matter most:

4.1.2 Name, Role, Value (Level A). The modal must have role="dialog" or role="alertdialog", and it must have an accessible name via aria-labelledby or aria-label.

2.4.3 Focus Order (Level A). When the modal opens, focus must move into it. When it closes, focus must return to the element that triggered it.

2.1.2 No Keyboard Trap (Level A). The user must be able to leave the modal using the keyboard. The Escape key must close the modal.

2.1.1 Keyboard (Level A). Every interactive element inside the modal must be operable with a keyboard.

2.4.7 Focus Visible (Level AA). Focus indicators must be visible inside the modal.

1.4.3 Contrast (Level AA). The modal's text, buttons, and links need to meet 4.5:1 contrast ratios.

Use the native dialog element

The single biggest improvement you can make is to use the HTML <dialog> element. When opened with .showModal(), it gives you focus trapping, Escape to close, return focus, and a top layer — all for free.

<button id="open-btn" onclick="document.getElementById('my-dialog').showModal()">
  Open settings
</button>

<dialog id="my-dialog" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Settings</h2>
  <p>Adjust your notification preferences below.</p>
  <form method="dialog">
    <label for="email-notifications">
      <input type="checkbox" id="email-notifications" checked>
      Email notifications
    </label>
    <button type="submit">Save</button>
  </form>
</dialog>
Enter fullscreen mode Exit fullscreen mode

No ARIA role needed (implicit). No JavaScript focus trap. No Escape key handler. No return-focus logic. Browser support is excellent across Chrome, Edge, Firefox, and Safari.

The close button problem

Almost every modal has an X button in the top-right corner. Almost every one of them is broken:

<!-- broken -->
<div class="close-btn" onclick="closeModal()">×</div>
Enter fullscreen mode Exit fullscreen mode

This fails three criteria at once: not a button (2.1.1), no accessible name (4.1.2), and not focusable (2.4.7).

The fix:

<!-- fixed -->
<button type="button" aria-label="Close" onclick="closeModal()">
  <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24">
    <path d="M18 6L6 18M6 6l12 12" stroke="currentColor" stroke-width="2"/>
  </svg>
</button>
Enter fullscreen mode Exit fullscreen mode

If you cannot use dialog: the manual checklist

  1. Add role="dialog" and aria-labelledby and aria-modal="true"
  2. Move focus into the modal on open
  3. Trap focus inside the modal (Tab/Shift+Tab cycle)
  4. Close on Escape
  5. Return focus to the trigger on close
  6. Make the backdrop inert with the inert attribute

Testing your modals in 5 minutes

Keyboard test: Tab to the trigger, press Enter. Does focus move into the modal? Does Tab cycle inside it? Does Escape close it? Does focus return?

Screen reader test: Turn on VoiceOver (Mac) or NVDA (Windows). Does it announce the dialog role and name? Can you navigate all content?

If either test fails at any step, you have a WCAG violation.

This is a cross-post from the AccessGuard blog where the full article includes detailed JavaScript code for manual focus trapping, alert dialog patterns, and a framework-by-framework breakdown (Bootstrap, React, SweetAlert, jQuery UI, Headless UI).

Want to check your own site? Run a free accessibility scan — no signup required.

Top comments (0)