HTML <dialog> element

The <dialog> element represents a dialog box, such as a confirmation prompt, a settings panel, or a message requiring a response. It holds the content and controls needed for that interaction and is normally hidden until opened.

A dialog can be non-modal or modal. A non-modal dialog allows the user to continue interacting with the rest of the page. It can be displayed by including the open attribute or by calling its show() method in JavaScript. A modal dialog, opened with showModal(), is placed above the page and makes the rest of that document inert, so that interaction is confined to the dialog until it closes. Adding open alone does not produce this modal behaviour.

HTML also provides a way to open a modal dialog without JavaScript. A <button> can use commandfor="dialogId" to identify the dialog and command="show-modal" to open it. The corresponding close command closes it. These button attributes require browser support; the JavaScript methods provide an alternative for older browsers.

A dialog can also be closed by its close() method or by submitting a <form method="dialog"> inside it. This form method closes the dialog without sending the form's data to a server. By default, a modal dialog also responds to a close request, such as pressing Escape. An explicit closing button gives the user a visible way to finish the interaction.

The closedby attribute controls automatic dismissal in supporting browsers. Its value closerequest permits a close request such as Escape, while any also permits a click outside the dialog to close it. The value none disables these automatic actions; closing buttons and script can still close the dialog. If the attribute is omitted, modal dialogs allow close requests and non-modal dialogs do not.

A modal dialog has a ::backdrop pseudo-element that can be styled with CSS to dim the area behind it. The dialog should also have an accessible name, for example by using aria-labelledby to refer to the id of its heading or prompt. The autofocus attribute can identify the control that should receive keyboard focus when the dialog opens.

When a button submits a form with method="dialog", its value becomes the dialog's JavaScript returnValue. Code can inspect that value when the dialog closes and decide what to do. Closing the dialog does not itself save settings or perform another application action. Escape does not submit a button value, so reset returnValue before reusing a dialog if you need to distinguish dismissal from a submitted choice.

The example opens a neutral choice dialog using showModal(). Choose Later or Ready to see the returned value, or press Escape to dismiss it. The script reports the result without performing another action. The declarative alternative for the opening button is commandfor="pf-demo-dialog" command="show-modal" in supporting browsers.

Attributes: open, closedby, GLOBALS. The command and commandfor attributes belong to the controlling button.

Typical layout:
<button type="button" id="pf-demo-open">Open dialog</button>
<dialog id="pf-demo-dialog" aria-labelledby="pf-demo-prompt">
  <p id="pf-demo-prompt">Ready to continue?</p>
  <form method="dialog">
    <button type="submit" value="later" autofocus>Later</button>
    <button type="submit" value="ready">Ready</button>
  </form>
</dialog>
<p id="pf-demo-result" role="status">No choice yet.</p>

Visual representation:

JavaScript for this example:
const demoDialog = document.getElementById('pf-demo-dialog');
const demoResult = document.getElementById('pf-demo-result');
document.getElementById('pf-demo-open').addEventListener('click', () => {
  demoDialog.returnValue = '';
  demoDialog.showModal();
});
demoDialog.addEventListener('close', () => {
  demoResult.textContent = demoDialog.returnValue
    ? 'Returned value: ' + demoDialog.returnValue
    : 'Dismissed without a choice.';
});