JavaScript Reference ยท DOM: Document and Elements
HTMLDialogElement
Reference for HTMLDialogElement: showModal(), show(), close(), returnValue, the close and cancel events, backdrop styling and accessibility notes.
The <dialog> element represents a dialog box or other interactive panel, and HTMLDialogElement is its JavaScript interface. showModal() opens it as a modal: the rest of the page becomes inert, focus moves into the dialog and stays there, the Esc key closes it and a ::backdrop is drawn behind it. show() opens it as a non-modal panel that sits in the normal flow.
Before this element, modals needed a lot of script to manage focus, scrolling and layering. Now the browser handles the top layer, focus trapping and the Esc key for you.
<dialog id="confirm"> <form method="dialog"> <p>Delete this file?</p> <button value="cancel">Cancel</button> <button value="yes">Delete</button> </form> </dialog>
confirm.showModal();
Try it
Syntax
dialog.show() dialog.showModal() dialog.close() dialog.close(returnValue) dialog.requestClose() dialog.open // boolean, reflects the open attribute dialog.returnValue // string
Parameters and members
| Name | Description |
|---|---|
show() |
Opens the dialog non-modally. |
showModal() |
Opens it modally in the top layer. |
close(returnValue) |
Closes it; the optional string is stored in returnValue. |
requestClose(returnValue) |
Newer: asks the dialog to close, firing cancel first so it can be prevented. |
open |
true while the dialog is open. |
returnValue |
String set by close() or by the value of the submit button of a method="dialog" form. |
Events
close fires after the dialog closes; cancel fires when the user requests closing (Esc) and can be cancelled in some cases; toggle/beforetoggle are newer additions.
Exceptions
showModal() throws InvalidStateError if the dialog is already open non-modally or is not connected to the document.
Usage notes
- Forms with
method="dialog"close the dialog on submit without sending anything, and setreturnValueto the submitter'svalue. This is the simplest way to build confirm dialogs. - Do not set the
openattribute for a modal. Doing so shows it non-modally, without backdrop or focus management. Always callshowModal(). - Backdrop clicks are not built in. The backdrop belongs to the dialog element, so a click on it reports
event.target === dialog. Clicks on the dialog's content report the inner element as the target, so comparing against the dialog itself, as in the example, detects backdrop clicks. Give the dialog no padding and put the padding on an inner element, because a click on the dialog's own padding also reports the dialog. - Focus. On open, the first focusable element (or the one with
autofocus) gets focus; when the dialog closes, focus returns to the element that had it before. Addautofocusto the safest action. - Scroll locking. Some sites add
overflow: hiddentobodywhile a modal is open to stop the page behind from scrolling. - Styling. Use
dialog::backdropanddialog[open]; animate opening with a CSS transition and@starting-style. - Accessibility. A modal
<dialog>has thedialogrole and is announced by screen readers. Give it an accessible name witharia-labelledbyand always provide a visible close control. - Nesting and stacking. Several modals can be open; the most recent is on top, and Esc closes only the topmost.
Browser support
<dialog> with showModal() and close() is supported in all current browsers. requestClose() and the closedby attribute are recent, so check a compatibility table.