HTML dialog element

Reference for the HTML dialog element: show versus showModal, the top layer, focus, and closing, including why Escape is not a universal rule.

标签页正文目前为英文。

The dialog element represents a dialog box or other interactive overlay. This page is the dedicated reference; dialog is not in the original tag catalog cards. The form page already notes method="dialog" and leaves the demonstration here instead of repeating that form model.

Both start and end tags are required. Permitted content is flow content. A dialog is closed in the markup when the open attribute is omitted. The open content attribute, or the show() method, opens a non-modal dialog. showModal() opens a modal dialog in the top layer and makes the rest of the document inert. Setting open in markup is not a substitute for showModal().

The example includes a local form with method="dialog" and no third-party action. The fragment was checked with Python 3.13's html.parser as a structural tree, and with the site build. show(), showModal(), focus movement, the top layer, and keyboard dismissal were not executed in a browser.

Official sources: MDN <dialog> element and the WHATWG HTML Living Standard. Fragments were checked with Python 3.13 html.parser. That parser builds an element tree; it is not a WHATWG conformance checker, and this is not a browser or accessibility test.

HTML tag catalog → · HTML tutorial overview →

show, showModal, and the top layer

Call show() for a non-modal dialog that does not take the modal top-layer role. Call showModal() for a modal dialog: the element is placed in the top layer, a backdrop can be painted, and the rest of the page is inert while it is open. Those APIs belong on the HTMLDialogElement interface and are not attributes in the markup.

The open attribute reflects whether the dialog is shown. Adding open in HTML, or setting it from script without showModal(), opens a non-modal dialog. Do not assume an open attribute produces a modal, inert-background experience.

Closing, focus, and Escape

A form inside a dialog may use method="dialog". Submitting that form closes the dialog and can set the dialog's returnValue from the submitting button's value. The form page mentions this method and does not duplicate the example.

A modal dialog can receive a close request, which user agents often map to the Escape key. That request fires a cancel event first; if the event is canceled, the dialog stays open. Do not generalize Escape as a close action for every dialog in every state. A dialog that is already closed, a non-modal dialog opened with show() or the open attribute, or a cancel handler that calls preventDefault can all behave differently. This page does not claim a key event was observed.

showModal() is specified to move focus into the dialog and to restore focus when the dialog closes. That focus cycle, inertness, and ::backdrop painting were not tested here.

A closed dialog with a local method=dialog form

<button type="button">Open</button>
<dialog>
  <form method="dialog">
    <button type="submit" value="close">Close</button>
  </form>
</dialog>

The dialog is closed in the markup. A nested form with method=dialog is a close control, not a remote submission.

AttributeDescription
openOmitted, so the dialog is closed in the markup. Adding open would show a non-modal dialog, not a showModal() top-layer dialog.
method (form)method="dialog" closes the dialog on submit and can set returnValue from the submitting button. It is not GET or POST and has no network endpoint.
  • There is no script in the fragment, so show() and showModal() are not called. There is no remote form action and no third-party image.
html
<button type="button" id="open-note">Open note</button>
<dialog id="note">
  <form method="dialog">
    <p>A practice note. This is not a live dialog test.</p>
    <button type="submit" value="close">Close</button>
  </form>
</dialog>

What this markup means

The dialog has no open attribute, so it is closed in the tree. The button is type=button, so it does not submit anything. The nested form uses method="dialog" and would close the dialog with returnValue close if it were submitted while the dialog was open. Opening the dialog still requires show() or showModal() in script, which this fragment does not run. Escape is not demonstrated and is not treated as a universal close key.

Related: <form> method and submission, <button>, <details>, HTML tag catalog

MDN documentation → · WHATWG HTML Standard →