HTML Reference Β· Interactive Elements
The <dialog> element
Reference for the HTML <dialog> element: showModal(), show() and close(), forms with method="dialog", ::backdrop, the closedby attribute and accessibility notes.
The <dialog> element represents a dialog box: a confirmation, a small form, an alert or any panel the user interacts with on top of the page. It is hidden until opened. Opened with showModal(), it becomes modal: it sits in the top layer above everything else, the rest of the page becomes inert, a ::backdrop covers the page, and Esc closes it. Opened with show(), it is non-modal and the page stays usable.
<dialog id="confirm"> <p>Delete this photo?</p> <form method="dialog"> <button value="cancel">Cancel</button> <button value="delete">Delete</button> </form> </dialog>
Try it
Submitting a form with method="dialog" closes the dialog instead of sending a request, and the value of the button that submitted it becomes the dialog's returnValue.
Attributes
| Attribute | Values | Description |
|---|---|---|
open |
Boolean | Present while the dialog is showing. Let the methods below manage it: adding open by hand shows the dialog without the focus handling and top-layer behavior that show() and showModal() provide. |
closedby |
any, closerequest, none |
Which user actions may close the dialog. any also allows light dismiss (clicking outside); closerequest allows Esc and other platform close requests; none allows only your own code. Modal dialogs default to closerequest, non-modal ones to none. Newer and not supported everywhere yet. |
It also accepts the global attributes. Don't put tabindex on the <dialog> element itself.
Methods, properties and events
| Member | Description |
|---|---|
showModal() |
Opens the dialog as a modal in the top layer, with a backdrop and an inert page. |
show() |
Opens the dialog as non-modal, in normal page flow. |
close(value) |
Closes the dialog; the optional value becomes returnValue. |
requestClose(value) |
Asks to close the dialog as if the user pressed Esc, so a cancel handler can still stop it. Newer than the other methods. |
returnValue |
A string describing how the dialog was closed. |
close event |
Fires after the dialog closes, however that happened. |
cancel event |
Fires when the user tries to dismiss the dialog (for example with Esc). Call preventDefault() to keep it open, such as when a form has unsaved changes. |
Usage notes
- Modal vs non-modal. Use
showModal()when the user must deal with the dialog before continuing. For a floating panel the user can ignore, useshow()or a popover. - Focus. When a dialog opens, the browser moves focus into it: to the element with
autofocus, or otherwise a sensible default such as the first focusable element. When it closes, focus usually returns to the element that opened it. - Give it a name. Point
aria-labelledbyat the dialog's heading, or usearia-label. For urgent messages that demand a response, addrole="alertdialog". - Always offer a visible close button. Touch devices have no Esc key, and not every user knows about it.
- Styling. Style the box like any element, the dimmed overlay with
::backdrop, and target open modals with the:modalpseudo-class. A closed dialog isdisplay: none, so an authordisplayrule ondialogkeeps it visible; scope such rules todialog[open]. - Declarative opening. Newer browsers can open and close dialogs from a button with no script using invoker commands (
commandfor="id"withcommand="show-modal"orcommand="close"). Check support before relying on them.
Technical summary
| Content categories | Flow content |
| Permitted content | Flow content |
| Tag omission | None; both the start and end tags are required |
| Permitted parents | Any element that accepts flow content |
| Implicit ARIA role | dialog |
| DOM interface | HTMLDialogElement |
| Default display | none; block while open |
Browser support
<dialog>, showModal(), show(), close(), ::backdrop and method="dialog" work in every current browser. The closedby attribute and requestClose() are recent additions that are not yet available in every browser, so treat them as enhancements.
Related
<form>βmethod="dialog"closes the surrounding dialog<button>β controls that open, submit and close dialogs<details>β a simpler show/hide widget- Lesson: Dialogs and Modals
- Lesson: Popovers