HTMLDialogElement
=================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`HTMLDialogElement`** interface provides methods to manipulate `<dialog>` elements. It inherits properties and methods from the `HTMLElement` interface.

EventTarget

Node

Element

HTMLElement

HTMLDialogElementInstance 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 string that sets or returns the return value for the dialog.

Instance methods
----------------

*Inherits methods from its parent, `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.

Events
------

*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.

`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"`.

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


```js
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 Standard # htmldialogelement |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The HTML element implementing this interface: `<dialog>`.