<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.
Accessibility considerations
The dialog
element still has compatibility issues with some forms of assistive technology, which may prevent people from reading or using dialog
element content. Because of this, it is advised to use an interim solution such as a11y-dialog until support improves.
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
<dialog open>
<p>Greetings, one and all!</p>
</dialog>
Advanced example
This example opens a pop-up dialog box that contains a form, when the "Update details" button is clicked.
HTML
<!-- Simple pop-up dialog box containing a form -->
<dialog id="favDialog">
<form method="dialog">
<p><label>Favorite animal:
<select>
<option></option>
<option>Brine shrimp</option>
<option>Red panda</option>
<option>Spider monkey</option>
</select>
</label></p>
<menu>
<button value="cancel">Cancel</button>
<button id="confirmBtn" value="default">Confirm</button>
</menu>
</form>
</dialog>
<menu>
<button id="updateDetails">Update details</button>
</menu>
<output aria-live="polite"></output>
JavaScript
var updateButton = document.getElementById('updateDetails');
var favDialog = document.getElementById('favDialog');
var outputBox = document.querySelector('output');
var selectEl = document.querySelector('select');
var confirmBtn = document.getElementById('confirmBtn');
// "Update details" button opens the <dialog> modally
updateButton.addEventListener('click', function onOpen() {
if (typeof favDialog.showModal === "function") {
favDialog.showModal();
} else {
alert("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