HTMLDialogElement: showModal() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2022.

The showModal() method of the HTMLDialogElement interface displays the dialog as a modal, over the top of any other dialogs that might be present. It displays in the top layer, along with a ::backdrop pseudo-element. Elements inside the same document as the dialog, except the dialog and its descendants, become inert (as if the inert attribute is specified). Only the containing document becomes blocked; if the dialog is rendered inside an iframe, the rest of the page remains interactive.

Syntax

showModal()

Parameters

None.

Return value

None (undefined).

Exceptions

InvalidStateError DOMException: Thrown if the dialog is already open and non-modal (i.e. if the dialog has already been opened with HTMLDialogElement.show()).

Examples

Opening a modal dialog

The following example shows a button that, when clicked, opens a modal <dialog> containing a form via the HTMLDialogElement.showModal() function. While open, everything other than the modal dialog's contents is inert. From there you can click the Cancel button to close the dialog (via the HTMLDialogElement.close() function), or submit the form via the submit button. Selecting the cancel button closes the dialog, creating a close event, not a cancel event.

HTML

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 type="submit">Confirm</button>
    </div>
  </form>
</dialog>

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

JavaScript

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

function openCheck(dialog) {
  if (dialog.open) {
    console.log("Dialog open");
  } else {
    console.log("Dialog closed");
  }
}

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

// Form cancel button closes the dialog box
cancelButton.addEventListener("click", () => {
  dialog.close("animalNotChosen");
  openCheck(dialog);
});

Result

Specifications

Specification
HTML # dom-dialog-showmodal-dev

Browser compatibility

BCD tables only load in the browser