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.
<div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 20%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 120" preserveAspectRatio="xMinYMin meet"><a xlink:href="/docs/Web/API/HTMLDialogElement" target="_top"><rect x="1" y="1" width="170" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text x="86" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLDialogElement</text></a></svg></div>
a:hover text { fill: #0095DD; pointer-events: all;}
Properties
Inherits properties from its parent, HTMLElement
.
HTMLDialogElement.open
- A
Boolean
reflecting theopen
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 thereturnValue
of the 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
Examples
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 | Status | Comment |
---|---|---|
HTML Living Standard The definition of 'HTMLDialogElement' in that specification. |
Living Standard | |
HTML 5.2 The definition of '<dialog>' in that specification. |
Recommendation | Initial definition |
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
HTMLDialogElement | Chrome Full support 37 | Edge Full support 79 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android
Full support
53
| Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
cancel event | Chrome Full support Yes | Edge Full support 79 | Firefox Full support 78 | IE No support No | Opera ? | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
close | Chrome Full support 37 | Edge Full support 79 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android
Full support
53
| Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
close event | Chrome Full support Yes | Edge Full support 79 | Firefox No support No | IE No support No | Opera ? | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
open | Chrome Full support 37 | Edge Full support 79 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android
Full support
53
| Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
returnValue | Chrome Full support 37 | Edge Full support 79 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android
Full support
53
| Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
show | Chrome Full support 37 | Edge Full support 79 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android
Full support
53
| Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
showModal | Chrome Full support 37 | Edge Full support 79 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android
Full support
53
| Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- Experimental. Expect behavior to change in the future.
- Experimental. Expect behavior to change in the future.
- See implementation notes.
- See implementation notes.
- User must explicitly enable this feature.
- User must explicitly enable this feature.
See also
- The HTML element implementing this interface:
<dialog>
.