HTMLDialogElement

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The HTMLDialogElement interface provides methods to manipulate <dialog> elements. It inherits properties and methods from the HTMLElement interface.

Properties

Inherits properties from its parent, HTMLElement.

HTMLDialogElement.open: A boolean value reflecting the open HTML attribute, indicating whether the dialog is available for interaction.
HTMLDialogElement.returnValue: A DOMString that sets or returns the return value for the dialog.

Methods

Inherits methods from its parent, HTMLElement.

HTMLDialogElement.close(): Closes the dialog. An optional DOMString 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. Interaction outside the dialog is blocked.

Events

cancel: Fired when the user instructs the browser that they wish to dismiss the current open dialog. Also available via the oncancel property.
close: Fired when the dialog is closed. Also available via the onclose property.

The following example shows a simple button that, when clicked, opens a <dialog> containing a form via the HTMLDialogElement.showModal() function. 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.

  <!-- Simple pop-up dialog box, containing a form -->
  <dialog id="favDialog">
    <form method="dialog">
      <section>
        <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>
      </section>
      <menu>
        <button id="cancel" type="reset">Cancel</button>
        <button type="submit">Confirm</button>
      </menu>
    </form>
  </dialog>

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

  <script>
    (function() {
      var updateButton = document.getElementById('updateDetails');
      var cancelButton = document.getElementById('cancel');
      var 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', function() {
        dialog.showModal();
        openCheck(dialog);
      });

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

    })();
  </script>

Note: You can find this example on GitHub as htmldialogelement-basic (see it live also).

Specifications

Specification
HTML Standard # htmldialogelement

Browser compatibility

BCD tables only load in the browser