-
Notifications
You must be signed in to change notification settings - Fork 22.4k
/
index.md
119 lines (87 loc) · 4.02 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
---
title: HTMLDialogElement
slug: Web/API/HTMLDialogElement
page-type: web-api-interface
browser-compat: api.HTMLDialogElement
---
{{APIRef("HTML DOM")}}
The **`HTMLDialogElement`** interface provides methods to manipulate {{HTMLElement("dialog")}} elements. It inherits properties and methods from the {{domxref("HTMLElement")}} interface.
{{InheritanceDiagram}}
## Instance properties
_Inherits properties from its parent, {{domxref("HTMLElement")}}._
- {{domxref("HTMLDialogElement.open")}}
- : A boolean value reflecting the [`open`](/en-US/docs/Web/HTML/Element/dialog#open) HTML attribute, indicating whether the dialog is available for interaction.
- {{domxref("HTMLDialogElement.returnValue")}}
- : A string that sets or returns the return value for the dialog.
## Instance methods
_Inherits methods from its parent, {{domxref("HTMLElement")}}._
- {{domxref("HTMLDialogElement.close()")}}
- : Closes the dialog. An optional string may be passed as an argument, updating the `returnValue` of the dialog.
- {{domxref("HTMLDialogElement.show()")}}
- : Displays the dialog modelessly, i.e. still allowing interaction with content outside of the dialog.
- {{domxref("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](/en-US/docs/Web/API/HTMLElement/inert) with interactions outside the dialog being blocked.
## Events
_Also inherits events from its parent interface, {{DOMxRef("HTMLElement")}}._
Listen to these events using {{DOMxRef("EventTarget.addEventListener", "addEventListener()")}} or by assigning an event listener to the `oneventname` property of this interface.
- {{domxref("HTMLDialogElement/close_event", "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"`](/en-US/docs/Web/HTML/Element/form#method).
## Examples
### Opening a modal dialog
The following example shows a button that, when clicked, opens a modal {{htmlelement("dialog")}} containing a form via the {{domxref("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 {{domxref("HTMLDialogElement.close()")}} function), or submit the form via the submit button. Selecting the cancel button closes the dialog, creating a {{domxref("HTMLDialogElement/close_event", "close")}} event, not a {{domxref("HTMLElement/cancel_event", "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
{{EmbedLiveSample("Opening a modal dialog")}}
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- The HTML element implementing this interface: {{ HTMLElement("dialog") }}.