a11y/dialog-native

Why

A div dialog needs a hand-written focus trap, Escape handling, a way to hide the rest of the page from screen readers, and focus return. Each is a common source of bugs. <dialog> with showModal() does all of it and is Baseline widely available.

Fix

Render <dialog>, open it with dialog.showModal() (modal) or dialog.show() (non-modal), close it with dialog.close() or a <form method="dialog">, and style the overlay with ::backdrop. Keep a component library's dialog if the project uses one; check it renders <dialog> or implements the APG pattern.

Examples

<!-- bad -->
<div class="modal" role="dialog" aria-modal="true">…</div>
<!-- good -->
<dialog aria-labelledby="t"><h2 id="t">Newsletter</h2>…</dialog>
<script type="module">document.querySelector('dialog').showModal()</script>

Sources

• MDN, the dialog element
• HTML Standard, the dialog element
• WAI-ARIA Authoring Practices, Dialog (Modal) pattern

Read it in the terminal

npx github:dawidolko/frontend-skills explain a11y/dialog-native