<dialog>
The <dialog> element represents a dialog box or other interactive component, such as a dismissible alert, inspector, or subwindow. It can be displayed as a modal (blocking interaction with the rest of the page) or non-modal. This native HTML element provides built-in accessibility features and keyboard handling for dialog interactions.
This page was last updated on 2025-11-17
Syntax
<dialog>
<h2>Dialog Title</h2>
<p>Dialog content here.</p>
<button>Close</button>
</dialog>
The element requires both opening and closing tags. By default, a dialog is hidden. Use JavaScript methods show(), showModal(), or close() to control visibility. Modal dialogs include a backdrop and trap focus within the dialog.
Attributes
- open - Boolean attribute indicating the dialog is active and can be interacted with. When absent, the dialog is hidden.
<dialog open>...</dialog>
- Global attributes - The <dialog> element supports all global attributes such as
id,class,style,lang, anddir.
JavaScript methods:
- show() - Opens as non-modal dialog
- showModal() - Opens as modal with backdrop
- close(returnValue) - Closes the dialog, optionally setting returnValue
JavaScript properties:
- open - Boolean reflecting the open attribute
- returnValue - String value passed to close() or from form submission
Examples
Simple Modal Dialog
<dialog id="myDialog">
<h2>Confirm Action</h2>
<p>Are you sure you want to proceed?</p>
<button onclick="this.closest('dialog').close('cancel')">Cancel</button>
<button onclick="this.closest('dialog').close('confirm')">Confirm</button>
</dialog>
<button onclick="document.getElementById('myDialog').showModal()">
Open Dialog
</button>
Dialog with Form
<dialog id="loginDialog">
<form method="dialog">
<h2>Login</h2>
<label>Username: <input type="text" name="user"></label>
<label>Password: <input type="password" name="pass"></label>
<button type="submit" value="login">Login</button>
<button type="submit" value="cancel">Cancel</button>
</form>
</dialog>
Styling the Backdrop
<style>
dialog::backdrop {
background: rgba(0, 0, 0, 0.5);
backdrop-filter: blur(3px);
}
</style>
When to Use
Use the <dialog> element when:
- Creating modal dialogs that require user interaction
- Building confirmation prompts or alerts
- Implementing login or signup forms in overlays
- Displaying important information that needs acknowledgment
- Creating image lightboxes or media previews
- Building settings panels or configuration dialogs
Do NOT use <dialog> when:
- Content should always be visible (use regular page content)
- Creating tooltips or small informational popups (use title or custom tooltips)
- Building navigation menus (use nav with appropriate patterns)
- The interaction doesn't warrant interrupting the user flow
Accessibility considerations:
- Modal dialogs automatically trap focus within the dialog
- Pressing Escape closes modal dialogs by default
- Screen readers announce when dialogs open
- Use aria-labelledby to connect dialog to its heading
- Ensure dialogs can be closed via keyboard
<dialog aria-labelledby="dialog-title">
<h2 id="dialog-title">Dialog Heading</h2>
...
</dialog>
