Skip to content
Tutorials Center
My learning

Topics

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.

HTML
<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

A modal dialog with a return value

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, use show() 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-labelledby at the dialog's heading, or use aria-label. For urgent messages that demand a response, add role="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 :modal pseudo-class. A closed dialog is display: none, so an author display rule on dialog keeps it visible; scope such rules to dialog[open].
  • Declarative opening. Newer browsers can open and close dialogs from a button with no script using invoker commands (commandfor="id" with command="show-modal" or command="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.