<dialog> Dialog
A dialog box or a modal window.
<dialog> is a popup box, such as a confirmation or a small form. The open attribute shows it as a non-modal box. More often a script calls showModal() to open it as a modal: the rest of the page goes inert, focus moves inside, and Esc closes it.
A form inside with method="dialog" closes the dialog on submit. Buttons can open it with no script through commandfor and command="show-modal". There must always be a visible way to close it.
show(), showModal() and close() are covered in the dialog element in the HTML Living Standard (opens in a new tab). Focus handling is taught in the Keyboard and Focus lesson.
Syntax
<dialog open>
<p>Message</p>
<form method="dialog">
<button>Close</button>
</form>
</dialog>When to use it
Confirming a deletion, signing in before checkout, picking an option in a short form, reading a serious warning: in each case the user has to deal with something before going on. That is a <dialog>. A modal dialog blocks the rest of the page, so keep it for moments worth the interruption.
Lighter overlays, like a menu, a hint or a share panel that should close when the user clicks away, suit the popover attribute. Content that expands in place is details. Long text such as terms and conditions reads better on a normal page, which people can also link to.
Setting the open state by hand has a catch. The open attribute, whether written in HTML or added by a script, always gives you a non-modal dialog. The page behind stays clickable, and focus stays where it was. A real modal needs showModal() or a button with command="show-modal". And a dialog that is open in the source shows up on every page load. Please don't use that for promotions nobody asked for.
Attributes
| Attribute | What it does |
|---|---|
open | Shows the dialog (non-modal). Prefer showModal() for modals. |
closedby | How it can be dismissed: any, closerequest or none. |
Live example
Edit the code and watch the preview.
<dialog open>
<p>Your changes were saved.</p>
<form method="dialog">
<button>OK</button>
</form>
</dialog>
<p>Page content behind the dialog.</p>More examples
Delete confirmation
aria-labelledby points to the heading, which gives the dialog its name. The two buttons live in a form with method="dialog". Either one closes the dialog, and a script can check which value was picked. Cancel is the safe option, so it comes first.
<dialog open aria-labelledby="del-title">
<h2 id="del-title">Delete this photo?</h2>
<p>This cannot be undone.</p>
<form method="dialog">
<button value="cancel">Cancel</button>
<button value="delete">Delete</button>
</form>
</dialog>Sign-in form in a dialog
This sign-in form posts to the server the way any form does. Cancel has formmethod="dialog" and formnovalidate. It closes the dialog, sends nothing and does not complain about the empty fields.
<dialog open aria-labelledby="login-title">
<h2 id="login-title">Sign in to continue</h2>
<form action="/login" method="post">
<label for="em">Email</label>
<input type="email" id="em" name="email" autocomplete="email" required>
<label for="pw">Password</label>
<input type="password" id="pw" name="password" autocomplete="current-password" required>
<button>Sign in</button>
<button formmethod="dialog" formnovalidate>Cancel</button>
</form>
</dialog>Tip: Every dialog needs a button that closes it.
Browser support
dialog is in the HTML Living Standard. All major browsers have supported it since 2022, showModal() and the ::backdrop pseudo-element included (dialog support (opens in a new tab)).
The closedby attribute decides whether a click outside or the Esc key closes the dialog. It is newer, and some browsers do not have it yet (closedby support (opens in a new tab)).
Accessibility
Open modals with showModal(). Focus then moves into the dialog and the page behind goes inert. Give the dialog an accessible name, and send focus back to the trigger once it closes. The W3C modal dialog pattern (opens in a new tab) covers focus management in detail.
Common mistakes
Wrong
<dialog open>Are you sure?</dialog>Right
<dialog id="confirm" aria-labelledby="ct">
<h2 id="ct">Are you sure?</h2>
<form method="dialog"><button>Close</button></form>
</dialog>open gives you a non-modal dialog. For a modal, call showModal(), and add a title and a close button.
Frequently asked questions
What is the difference between show() and showModal()?
showModal() opens a modal. The dialog goes into the top layer, the rest of the page turns inert, a ::backdrop covers the page, and Escape closes it. show() opens a non-modal dialog, and users can keep working with the page. Most popups that need an answer should use showModal(). Can I use (opens in a new tab) tracks browser support.
How do I close a dialog without JavaScript?
Put a form with method="dialog" inside it. Submitting that form, say with <button>Close</button>, closes the dialog and sets its returnValue to the button's value. Escape also closes modal dialogs. Newer browsers add closedby="any" for closing on a backdrop click, plus invoker commands that open and close dialogs with no script.