{
    "slug": "html_dialog_element",
    "term": "Native dialog Element",
    "category": "frontend",
    "difficulty": "beginner",
    "short": "The HTML dialog element provides accessible modals and non-modal dialogs natively — with built-in focus trapping, backdrop rendering, and the Escape key — without JavaScript libraries.",
    "long": "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.",
    "aliases": [
        "dialog element",
        "showModal",
        "HTML modal",
        "native modal"
    ],
    "tags": [
        "frontend",
        "html",
        "accessibility"
    ],
    "misconception": "Native dialog is less flexible than a custom modal — native dialog handles all accessibility requirements out of the box; custom modals require extensive ARIA attributes, focus management, and keyboard handling that dialog provides automatically.",
    "why_it_matters": "Custom modal implementations that miss focus trapping or Escape key handling fail accessibility requirements — the native dialog element handles these correctly without any extra code.",
    "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."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "accessibility_aria",
        "focus_management",
        "keyboard_navigation"
    ],
    "prerequisites": [
        "html_accessibility",
        "focus_management",
        "keyboard_navigation"
    ],
    "refs": [
        "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog"
    ],
    "bad_code": "<!-- Custom modal — manual accessibility:\n<div id=\"modal\" role=\"dialog\" aria-modal=\"true\" style=\"display:none\">\n    <!-- Manual focus trap needed -->\n    <!-- Manual Escape key handler needed -->\n    <!-- Manual ARIA management needed -->\n    <!-- 50 lines of JS for what dialog does natively -->\n</div>",
    "good_code": "<!-- Native dialog — automatic accessibility:\n<dialog id=\"confirm\">\n    <h2>Confirm deletion?</h2>\n    <p>This cannot be undone.</p>\n    <form method=\"dialog\">\n        <button value=\"cancel\">Cancel</button>\n        <button value=\"confirm\">Delete</button>\n    </form>\n</dialog>\n\n<button onclick=\"document.getElementById('confirm').showModal()\">\n    Delete\n</button>\n\n<script>\n    document.getElementById('confirm').addEventListener('close', e => {\n        if (e.target.returnValue === 'confirm') deleteItem();\n    });\n</script>",
    "quick_fix": "Use the native <dialog> element instead of DIV-based modal implementations — it handles focus trapping, Escape key, and screen reader announcement automatically",
    "severity": "medium",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/html_dialog_element",
        "html_url": "https://codeclaritylab.com/glossary/html_dialog_element",
        "json_url": "https://codeclaritylab.com/glossary/html_dialog_element.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Native dialog Element](https://codeclaritylab.com/glossary/html_dialog_element) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/html_dialog_element"
            }
        }
    }
}