HTMLDialogElement

Also inherits properties from its parent interface, HTMLElement.

HTMLDialogElement.open

A boolean value reflecting the open HTML attribute, indicating whether the dialog is available for interaction.

HTMLDialogElement.returnValue

A string that sets or returns the return value for the dialog.

Also inherits methods from its parent interface, HTMLElement.

HTMLDialogElement.close()

Closes the dialog. An optional string may be passed as an argument, updating the returnValue of the dialog.

HTMLDialogElement.show()

Displays the dialog modelessly, i.e. still allowing interaction with content outside of the dialog.

HTMLDialogElement.showModal()

Displays the dialog as a modal, over the top of any other dialogs that might be present. Everything outside the dialog are inert with interactions outside the dialog being blocked.

Also inherits events from its parent interface, HTMLElement.

Listen to these events using addEventListener() or by assigning an event listener to the oneventname property of this interface.

cancel

Fired when the user dismisses the current open dialog with the escape key.

close

Fired when the dialog is closed, whether with the escape key, the HTMLDialogElement.close() method, or via submitting a form within the dialog with method="dialog".

The following example shows a button that, when clicked, uses the HTMLDialogElement.showModal() function to open a modal <dialog> containing a form.

While open, everything other than the modal dialog's contents is inert. You can click the Cancel button to close the dialog (via the HTMLDialogElement.close() function), or submit the form via the Confirm button.

The example demonstrates how you might use all the "state change" events that can be fired on the dialog: cancel and close, and the inherited events beforetoggle, and toggle.

HTML

<!-- pop-up dialog box, containing a form -->
<dialog id="favDialog">
  <form method="dialog">
    <p>
      <label for="favAnimal">Favorite animal:</label>
      <select id="favAnimal" name="favAnimal">
        <option></option>
        <option>Brine shrimp</option>
        <option>Red panda</option>
        <option>Spider monkey</option>
      </select>
    </p>
    <div>
      <button id="cancel" type="reset">Cancel</button>
      <button id="submit" type="submit">Confirm</button>
    </div>
  </form>
</dialog>

<div>
  <button id="updateDetails">Update details</button>
</div>

<pre id="log"></pre>

#log {
  height: 150px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

Showing the dialog

The code first gets objects for the <button> elements, the <dialog> element, and the <select> element. It then adds a listener to call the HTMLDialogElement.showModal() function when the Update button is clicked.

const updateButton = document.getElementById("updateDetails");
const confirmButton = document.getElementById("submit");
const cancelButton = document.getElementById("cancel");
const dialog = document.getElementById("favDialog");
const selectElement = document.getElementById("favAnimal");

// Update button opens a modal dialog
updateButton.addEventListener("click", () => {
  dialog.showModal();
});

Cancel and confirm buttons

Next we add listeners to the Confirm and Cancel button click events. The handlers call HTMLDialogElement.close() with the selection value (if present) and no value, which in turn set the return value of the dialog (HTMLDialogElement.returnValue) to the selection value and null, respectively.

// Confirm button closes dialog if there is a selection.
confirmButton.addEventListener("click", () => {
  if (selectElement.value) {
    //Set dialog.returnValue to selected value
    dialog.close(selectElement.value);
  }
});

// Cancel button closes the dialog box
cancelButton.addEventListener("click", () => {
  dialog.close(); // Set dialog.returnValue to null
});

Calling close() also fires the close event, which we implement below by logging the return value of the dialog. If the Confirm button was clicked this should be the selected value in the dialog, otherwise it should be null.

dialog.addEventListener("close", (event) => {
  log(`close_event: (dialog.returnValue: "${dialog.returnValue}")`);
});

Cancel event

The cancel event is fired when "platform specific methods" are used to close the dialog, such as the Esc key. The event is "cancelable" which means that we could use it to prevent the dialog from closing. Here we just treat the cancel as a "close" operation, and reset the HTMLDialogElement.returnValue to "" to clear any value that may have been set.

dialog.addEventListener("cancel", (event) => {
  log(`cancel_event: (dialog.returnValue: "${dialog.returnValue}")`);
  dialog.returnValue = ""; //Reset value
});

Toggle event

The toggle event (inherited from HTMLElement) is fired just after a dialog has opened or closed (but before the closed event).

Here we add a listener to log when the Dialog opens and closes.

dialog.addEventListener("toggle", (event) => {
  log(`toggle_event: Dialog ${event.newState}`);
});

Beforetoggle event

The beforetoggle event (inherited from HTMLElement) is a cancellable event that is fired just before a dialog is opened or closed. If needed, this can be used to prevent a dialog from showing, or to perform actions on other elements that are affected by the dialog open/close state, such as adding classes on them to trigger animations.

In this case we just log the old and new state.

dialog.addEventListener("beforetoggle", (event) => {
  log(
    `beforetoggle event: oldstate: ${event.oldState}, newState: ${event.newState}`,
  );

  // Call event.preventDefault() to prevent a dialog opening
  /*
    if (shouldCancel()) {
        event.preventDefault();
    }
  */
});

Result

Try out the example below. Note that both Confirm and Cancel buttons result in the close event being fired, and that the result should reflect the selected dialog option.

• The HTML element implementing this interface: <dialog>.