<dialog>: The Dialog element
The <dialog>
HTML element represents a dialog box or other interactive component, such as a dismissible alert, inspector, or subwindow.
Content categories | Flow content, sectioning root |
---|---|
Permitted content | Flow content |
Tag omission | None, both the starting and ending tag are mandatory. |
Permitted parents | Any element that accepts flow content |
Implicit ARIA role | dialog |
Permitted ARIA roles | alertdialog |
DOM interface | HTMLDialogElement |
Attributes
This element includes the global attributes.
Warning: The tabindex
attribute must not be used on the <dialog>
element.
open
-
Indicates that the dialog is active and can be interacted with. When the
open
attribute is not set, the dialog shouldn't be shown to the user. It is recommended to use the.show()
or.showModal()
methods to render dialogs, rather than theopen
attribute.
Accessibility considerations
The dialog
element still has usability issues with some forms of assistive technology. Because of this, it is advised to use an interim solution such as a11y-dialog as support continues to improve.
Usage notes
<form>
elements can close a dialog if they have the attributemethod="dialog"
. When such a form is submitted, the dialog closes with itsreturnValue
property set to thevalue
of the button that was used to submit the form.- The
::backdrop
CSS pseudo-element can be used to style behind a<dialog>
element when the dialog is displayed withHTMLDialogElement.showModal()
. For example, to dim unreachable content behind the modal dialog.
Examples
Simple example
The following will render a modeless (non-modal) dialog. The "OK" button allows the dialog to be closed when activated. It is important to provide a mechanism to close a dialog within the dialog
element. For instance, the Esc key does not close modeless dialogs by default, nor can one assume that a user will even have access to a physical keyboard (e.g., someone using a touch screen device without access to a keyboard).
<dialog open>
<p>Greetings, one and all!</p>
<form method="dialog">
<button>OK</button>
</form>
</dialog>
Advanced example
This example opens a modal dialog that contains a form, when the "Update details" button is activated.
HTML
<!-- Simple modal dialog containing a form -->
<dialog id="favDialog">
<form method="dialog">
<p><label>Favorite animal:
<select>
<option value="default">Choose...</option>
<option>Brine shrimp</option>
<option>Red panda</option>
<option>Spider monkey</option>
</select>
</label></p>
<div>
<button value="cancel">Cancel</button>
<button id="confirmBtn" value="default">Confirm</button>
</div>
</form>
</dialog>
<p>
<button id="updateDetails">Update details</button>
</p>
<output></output>
JavaScript
const updateButton = document.getElementById('updateDetails');
const favDialog = document.getElementById('favDialog');
const outputBox = document.querySelector('output');
const selectEl = favDialog.querySelector('select');
const confirmBtn = favDialog.querySelector('#confirmBtn');
// If a browser doesn't support the dialog, then hide the
// dialog contents by default.
if ( typeof favDialog.showModal !== 'function' ) {
favDialog.hidden = true;
/* a fallback script to allow this dialog/form to function
for legacy browsers that do not support <dialog>
could be provided here.
*/
}
// "Update details" button opens the <dialog> modally
updateButton.addEventListener('click', function onOpen() {
if (typeof favDialog.showModal === "function") {
favDialog.showModal();
} else {
outputBox.value = "Sorry, the <dialog> API is not supported by this browser.";
}
});
// "Favorite animal" input sets the value of the submit button
selectEl.addEventListener('change', function onSelect(e) {
confirmBtn.value = selectEl.value;
});
// "Confirm" button of form triggers "close" on dialog because of [method="dialog"]
favDialog.addEventListener('close', function onClose() {
outputBox.value = favDialog.returnValue + " button clicked - " + (new Date()).toString();
});
Result
Specifications
Specification |
---|
HTML Standard # the-dialog-element |
Browser compatibility
BCD tables only load in the browser
See also
- The
close
event - The
cancel
event - HTML forms guide.
- The
::backdrop
pseudo-element - dialog-polyfill