HTMLDialogElement
The HTMLDialogElement interface provides methods to manipulate elements. It inherits properties and methods from the HTMLElement interface.
Instance properties
Also inherits properties from its parent interface, HTMLElement.
HTMLDialogElement.closedByExperimental-
A string that sets or returns the
closedbyattribute value of theelement, which indicates the types of user actions that can be used to close the dialog. HTMLDialogElement.open-
A boolean value reflecting the
openHTML 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
Also inherits methods from its parent interface, HTMLElement.
HTMLDialogElement.close()-
Closes the dialog. An optional string may be passed as an argument, updating the
returnValueof the dialog. HTMLDialogElement.requestClose()-
Requests to close the dialog. An optional string may be passed as an argument, updating the
returnValueof 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.
cancel-
Fired when the dialog is requested to close, whether with the escape key, or via the
HTMLDialogElement.requestClose()method. close-
Fired when the dialog is closed, whether with the escape key, the
HTMLDialogElement.close()method, or via submitting a form within the dialog withmethod="dialog".
Examples
Opening a modal dialog
The following example shows a button that, when clicked, uses the HTMLDialogElement.showModal() function to open a modal 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
JavaScript
Showing the dialog
The code first gets objects for the elements, the element, and the 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.
It is also fired when the HTMLDialogElement.requestClose() method is called.
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.
Note:
The toggle and beforetoggle events may not be fired at dialog elements on all browsers.
On these browser versions you can instead check the HTMLDialogElement.open property after attempting to open/close the dialog.
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.
Specifications
| Specification |
|---|
| HTML # htmldialogelement |
| HTML # event-beforetoggle |
| HTML # event-toggle |