Native dialog Element

Also Known As

TL;DR

Explanation

The dialog element renders a modal (when opened with showModal()) or non-modal dialog (show()). Features: automatic focus trapping (Tab cycles within), backdrop pseudo-element (::backdrop for overlay styling), Escape key closes modal automatically, returnValue for form results, and correct ARIA semantics (role=dialog, aria-modal). Close with dialog.close() or a form method=dialog button. The dialog element replaced dozens of JS modal libraries — it handles all the accessibility requirements that were previously hand-coded.

Common Misconception

Why It Matters

Common Mistakes

• Using show() when a modal (focus-trapped) is needed — use showModal() for modal dialogs.
• Not styling ::backdrop — the default backdrop is transparent; add a semi-transparent background.
• Placing dialog outside the modal stack — always append dialog to document.body.
• Not calling dialog.close() on confirm/cancel buttons — dialog stays open without explicit close.

Code Examples

<!-- Custom modal — manual accessibility:
<div id="modal" role="dialog" aria-modal="true" style="display:none">
    <!-- Manual focus trap needed -->
    <!-- Manual Escape key handler needed -->
    <!-- Manual ARIA management needed -->
    <!-- 50 lines of JS for what dialog does natively -->
</div>

<!-- Native dialog — automatic accessibility:
<dialog id="confirm">
    <h2>Confirm deletion?</h2>
    <p>This cannot be undone.</p>
    <form method="dialog">
        <button value="cancel">Cancel</button>
        <button value="confirm">Delete</button>
    </form>
</dialog>

<button onclick="document.getElementById('confirm').showModal()">
    Delete
</button>

<script>
    document.getElementById('confirm').addEventListener('close', e => {
        if (e.target.returnValue === 'confirm') deleteItem();
    });
</script>

References

• ↗ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog

Tags

Related Terms