Skip to content
Tutorials Center
My learning

Topics

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.

HTML
<dialog id="confirm">
  <form method="dialog">
    <p>Delete this file?</p>
    <button value="cancel">Cancel</button>
    <button value="yes">Delete</button>
  </form>
</dialog>
JavaScript
confirm.showModal();

Try it

A modal with a result
Close on backdrop click and cancel event

Syntax

JavaScript
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 set returnValue to the submitter's value. This is the simplest way to build confirm dialogs.
  • Do not set the open attribute for a modal. Doing so shows it non-modally, without backdrop or focus management. Always call showModal().
  • 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. Add autofocus to the safest action.
  • Scroll locking. Some sites add overflow: hidden to body while a modal is open to stop the page behind from scrolling.
  • Styling. Use dialog::backdrop and dialog[open]; animate opening with a CSS transition and @starting-style.
  • Accessibility. A modal <dialog> has the dialog role and is announced by screen readers. Give it an accessible name with aria-labelledby and 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.