diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/html/element%2Fdialog.html | |
new repository
Diffstat (limited to 'devdocs/html/element%2Fdialog.html')
| -rw-r--r-- | devdocs/html/element%2Fdialog.html | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/devdocs/html/element%2Fdialog.html b/devdocs/html/element%2Fdialog.html new file mode 100644 index 00000000..9cdc464f --- /dev/null +++ b/devdocs/html/element%2Fdialog.html @@ -0,0 +1,225 @@ +<header><h1><dialog>: The Dialog element</h1></header><div class="section-content"> +<p>The <code><dialog></code> <a href="../index">HTML</a> element represents a modal or non-modal dialog box or other interactive component, such as a dismissible alert, inspector, or subwindow.</p> <p>The HTML <code><dialog></code> element is used to create both modal and non-modal dialog boxes. Modal dialog boxes interrupt interaction with the rest of the page being inert, while non-modal dialog boxes allow interaction with the rest of the page.</p> <p>JavaScript should be used to display the <code><dialog></code> element. Use the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal"><code>.showModal()</code></a> method to display a modal dialog and the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/show"><code>.show()</code></a> method to display a non-modal dialog. The dialog box can be closed using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close"><code>.close()</code></a> method or using the <a href="form#method"><code>dialog</code></a> method when submitting a <code><form></code> that is nested within the <code><dialog></code> element. Modal dialogs can also be closed by pressing the <kbd>Esc</kbd> key.</p> +</div> +<h2 id="attributes">Attributes</h2> +<div class="section-content"> +<p>This element includes the <a href="../global_attributes">global attributes</a>.</p> <div class="notecard warning" id="sect1"> <p><strong>Warning:</strong> The <code>tabindex</code> attribute must not be used on the <code><dialog></code> element.</p> </div> <dl> <dt id="open"><a href="#open"><code>open</code></a></dt> <dd> <p> Indicates that the dialog box is active and is available for interaction. If the <code>open</code> attribute is not set, the dialog box will not be visible to the user. It is recommended to use the <code>.show()</code> or <code>.showModal()</code> method to render dialogs, rather than the <code>open</code> attribute. If a <code><dialog></code> is opened using the <code>open</code> attribute, it is non-modal. </p> <div class="notecard note" id="sect2"> <p><strong>Note:</strong> While you can toggle between the open and closed states of non-modal dialog boxes by toggling the presence of the <code>open</code> attribute, this approach is not recommended.</p> </div> </dd> </dl> +</div> +<h2 id="usage_notes">Usage notes</h2> +<div class="section-content"><ul> <li>HTML <a href="form"><code><form></code></a> elements can be used to close a dialog box if they have the attribute <code>method="dialog"</code> or if the button used to submit the form has <a href="input#formmethod"><code>formmethod="dialog"</code></a> set. When a <code><form></code> within a <code><dialog></code> is submitted via the <code>dialog</code> method, the dialog box closes, the states of the form controls are saved but not submitted, and the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue"><code>returnValue</code></a> property gets set to the value of the button that was activated.</li> <li>The CSS <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/::backdrop"><code>::backdrop</code></a> pseudo-element can be used to style the backdrop of a modal dialog, which is displayed behind the <code><dialog></code> element when the dialog is displayed using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal"><code>HTMLDialogElement.showModal()</code></a> method. For example, you can use this pseudo-element to obfuscate the inert content behind the modal dialog.</li> <li>The <a href="../global_attributes/autofocus"><code>autofocus</code></a> attribute should be added to the element with which the user is expected to interact immediately on opening a modal dialog. If there is no element involving immediate interaction, the <code>autofocus</code> attribute can be added to the <code><dialog></code> element itself.</li> </ul></div> +<h2 id="examples">Examples</h2> + +<h3 id="caveats_of_creating_a_dialog_using_only_html">Caveats of creating a dialog using only HTML</h3> +<div class="section-content"> +<p>This example demonstrates the create a non-modal dialog by using only HTML. Because of the boolean <code>open</code> attribute in the <code><dialog></code> element, the dialog appears open when the page loads. The dialog can be closed by clicking the "OK" button because the <code>method</code> attribute in the <code><form></code> element is set to <code>"dialog"</code>. In this case, no JavaScript is needed to close the form.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="pyNIZ2FRkQ0lF2puOc9mOyM0N5EGixmK3+Oo9MoGK7Y=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dialog</span> <span class="token attr-name">open</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>Greetings, one and all!<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>form</span> <span class="token attr-name">method</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>dialog<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span><span class="token punctuation">></span></span>OK<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>form</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dialog</span><span class="token punctuation">></span></span> +</pre> +</div> <h4 id="result">Result</h4> +<div class="code-example" id="sect3"> + +<iframe class="sample-code-frame" title="Caveats of creating a dialog using only HTML sample" id="frame_caveats_of_creating_a_dialog_using_only_html" width="100%" height="200" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dialog/runner.html?id=caveats_of_creating_a_dialog_using_only_html" loading="lazy"></iframe> +</div> <p>This dialog is initially open because of the presence of the <code>open</code> attribute. Dialogs that are displayed using the <code>open</code> attribute are non-modal. You may notice that after clicking "OK", the dialog gets dismissed leaving the Result frame empty. When the dialog is dismissed, there is no method provided to reopen it. For this reason, the preferred method to display non-modal dialogs is by using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/show"><code>HTMLDialogElement.show()</code></a> method. It is possible to toggle the display of the dialog by adding or removing the boolean <code>open</code> attribute, but it is not the recommended practice.</p> +</div> +<h3 id="creating_a_modal_dialog">Creating a modal dialog</h3> +<div class="section-content"> +<p>This example demonstrates a modal dialog with a <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/gradient">gradient</a> backdrop. The <code>.showModal()</code> method opens the modal dialog when the "Show the dialog" button is activated. The dialog can be closed by pressing the <kbd>Esc</kbd> key or via the <code>close()</code> method when the "Close" button within the dialog is activated.</p> <p>When a dialog opens, the browser, by default, gives focus to the first element that can be focused within the dialog. In this example, the <a href="../global_attributes/autofocus"><code>autofocus</code></a> attribute is applied to the "Close" button, giving it focus when the dialog opens, as this is the element we expect the user will interact with immediately after the dialog opens.</p> <h4 id="html">HTML</h4> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="Xv9c7iVVc1F4wwPfrGwHu071HTJUDNf6iLXjLHE1Puo=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dialog</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span> <span class="token attr-name">autofocus</span><span class="token punctuation">></span></span>Close<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>This modal dialog has a groovy backdrop!<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dialog</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span><span class="token punctuation">></span></span>Show the dialog<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> +</pre> +</div> <h4 id="css">CSS</h4> <p>We can style the backdrop of the dialog by using the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/::backdrop"><code>::backdrop</code></a> pseudo-element.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">css</span></p> +<pre data-signature="sqXwO2T9Od4FEjsRw7i0W3dcJPvVkka/x3dV/ZLpWTk=" data-language="css"><span class="token selector">::backdrop</span> <span class="token punctuation">{</span> + <span class="token property">background-image</span><span class="token punctuation">:</span> <span class="token function">linear-gradient</span><span class="token punctuation">(</span> + 45deg<span class="token punctuation">,</span> + magenta<span class="token punctuation">,</span> + rebeccapurple<span class="token punctuation">,</span> + dodgerblue<span class="token punctuation">,</span> + green + <span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token property">opacity</span><span class="token punctuation">:</span> 0.75<span class="token punctuation">;</span> +<span class="token punctuation">}</span> +</pre> +</div> <h4 id="javascript">JavaScript</h4> <p>The dialog is opened modally using the <code>.showModal()</code> method and closed using the <code>.close()</code> method.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="vmyF0hgKihq9VvJn2x4/cEi1aTThye/GsJnxYTOvRTs=" data-language="js"><span class="token keyword">const</span> dialog <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"dialog"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> showButton <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"dialog + button"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> closeButton <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"dialog button"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token comment">// "Show the dialog" button opens the dialog modally</span> +showButton<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + dialog<span class="token punctuation">.</span><span class="token function">showModal</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token comment">// "Close" button closes the dialog</span> +closeButton<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + dialog<span class="token punctuation">.</span><span class="token function">close</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +</pre> +</div> <h4 id="result_2">Result</h4> +<div class="code-example" id="sect4"> + +<iframe class="sample-code-frame" title="Creating a modal dialog" id="frame_modal_example" width="100%" height="200" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dialog/runner.html?id=modal_example" loading="lazy"></iframe> +</div> <p>When the modal dialog is displayed, it appears above any other dialogs that might be present. Everything outside the modal dialog is inert and interactions outside the dialog are blocked. Notice that when the dialog is open, with the exception of the dialog itself, interaction with the document is not possible; the "Show the dialog" button is mostly obfuscated by the almost opaque backdrop of the dialog and is inert.</p> +</div> +<h3 id="handling_the_return_value_from_the_dialog">Handling the return value from the dialog</h3> +<div class="section-content"> +<p>This example demonstrates the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue"><code>returnValue</code></a> of the <code><dialog></code> element and how to close a modal dialog by using a form. By default, the <code>returnValue</code> is the empty string or the value of the button that submits the form within the <code><dialog></code> element, if there is one.</p> <p>This example opens a modal dialog when the "Show the dialog" button is activated. The dialog contains a form with a <a href="select"><code><select></code></a> and two <a href="button"><code><button></code></a> elements, which default to <code>type="submit"</code>. An eventlistener updates the value of the "Confirm" button when the select option changes. If the "Confirm" button is activated to close the dialog, the current value of the button is the return value. If the dialog is closed by pressing the "Cancel" button, the <code>returnValue</code> is <code>cancel</code>.</p> <p>When the dialog is closed, the return value is displayed under the "Show the dialog" button. If the dialog is closed by pressing the <kbd>Esc</kbd> key, the <code>returnValue</code> is not updated and the <code>close</code> event doesn't occur so the text in the <a href="output"><code><output></code></a> is not updated.</p> <h4 id="html_2">HTML</h4> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="Ci7v1IxOdLaATtDpSBzqImRutC478hodwNiENAyBDsA=" data-language="html"><span class="token comment"><!-- A modal dialog containing a form --></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>dialog</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>favDialog<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>form</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span><span class="token punctuation">></span></span> + Favorite animal: + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>select</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>option</span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>default<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Choose…<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>option</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>option</span><span class="token punctuation">></span></span>Brine shrimp<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>option</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>option</span><span class="token punctuation">></span></span>Red panda<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>option</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>option</span><span class="token punctuation">></span></span>Spider monkey<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>option</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>select</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>cancel<span class="token punctuation">"</span></span> <span class="token attr-name">formmethod</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>dialog<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Cancel<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>confirmBtn<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>default<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Confirm<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>form</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>dialog</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>showDialog<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Show the dialog<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>output</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>output</span><span class="token punctuation">></span></span> +</pre> +</div> <h4 id="javascript_2">JavaScript</h4> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="BRvGCaqoGfnwSoPFBO1mMlbIWtQ3mmDiFE2oskAktIk=" data-language="js"><span class="token keyword">const</span> showButton <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">getElementById</span><span class="token punctuation">(</span><span class="token string">"showDialog"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> favDialog <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">getElementById</span><span class="token punctuation">(</span><span class="token string">"favDialog"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> outputBox <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"output"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> selectEl <span class="token operator">=</span> favDialog<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"select"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> confirmBtn <span class="token operator">=</span> favDialog<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"#confirmBtn"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token comment">// "Show the dialog" button opens the <dialog> modally</span> +showButton<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + favDialog<span class="token punctuation">.</span><span class="token function">showModal</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token comment">// "Favorite animal" input sets the value of the submit button</span> +selectEl<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"change"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">e</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + confirmBtn<span class="token punctuation">.</span>value <span class="token operator">=</span> selectEl<span class="token punctuation">.</span>value<span class="token punctuation">;</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token comment">// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"], triggering a close event.</span> +favDialog<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"close"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">e</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + outputBox<span class="token punctuation">.</span>value <span class="token operator">=</span> + favDialog<span class="token punctuation">.</span>returnValue <span class="token operator">===</span> <span class="token string">"default"</span> + <span class="token operator">?</span> <span class="token string">"No return value."</span> + <span class="token operator">:</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">ReturnValue: </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>favDialog<span class="token punctuation">.</span>returnValue<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">.</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">;</span> <span class="token comment">// Have to check for "default" rather than empty string</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token comment">// Prevent the "confirm" button from the default behavior of submitting the form, and close the dialog with the `close()` method, which triggers the "close" event.</span> +confirmBtn<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">event</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + event<span class="token punctuation">.</span><span class="token function">preventDefault</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// We don't want to submit this fake form</span> + favDialog<span class="token punctuation">.</span><span class="token function">close</span><span class="token punctuation">(</span>selectEl<span class="token punctuation">.</span>value<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Have to send the select box value here.</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +</pre> +</div> +</div> +<h3 id="result_3">Result</h3> +<div class="section-content"> +<div class="code-example" id="sect5"> + +<iframe class="sample-code-frame" title="Handling the return value from the dialog sample" id="frame_handling_the_return_value_from_the_dialog" width="100%" height="300" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/dialog/runner.html?id=handling_the_return_value_from_the_dialog" loading="lazy"></iframe> +</div> <p>This example demonstrates the following three methods of closing modal dialogs:</p> <ul> <li>By submitting the form within the dialog form using the <code>dialog</code> method (as seen in the <a href="#caveats-of-creating-a-dialog-using-only-html">HTML-only example</a>).</li> <li>By pressing the <kbd>Esc</kbd> key.</li> <li> By calling the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close"><code>HTMLDialogElement.close()</code></a> method (as seen in the <a href="#creating_a_modal_dialog">modal example</a>. In this example, the "Cancel" button closes the dialog via the <code>dialog</code> form method and the "Confirm" button closes the dialog via the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close"><code>HTMLDialogElement.close()</code></a> method. </li> </ul> <p>The "Cancel" button includes the <a href="input/submit#formmethod"><code>formmethod="dialog"</code></a> attribute, which overrides the <a href="form"><code><form></code></a>'s default <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET"><code>GET</code></a> method. When a form's method is <a href="#usage_notes"><code>dialog</code></a>, the state of the form is saved but not submitted, and the dialog gets closed.</p> <p>Without an <code>action</code>, submitting the form via the default <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET"><code>GET</code></a> method causes a page to reload. We use JavaScript to prevent the submission and close the dialog with the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault"><code>event.preventDefault()</code></a> and <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close"><code>HTMLDialogElement.close()</code></a> methods, respectively.</p> <p>It is important to provide a closing mechanism within every <code>dialog</code> element. The <kbd>Esc</kbd> key does not close non-modal 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).</p> +</div> +<h2 id="technical_summary">Technical summary</h2> +<div class="section-content"><figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <th scope="row"><a href="../content_categories">Content categories</a></th> <td> <a href="../content_categories#flow_content">Flow content</a>, <a href="heading_elements#sectioning_roots">sectioning root</a> </td> </tr> <tr> <th scope="row">Permitted content</th> <td><a href="../content_categories#flow_content">Flow content</a></td> </tr> <tr> <th scope="row">Tag omission</th> <td>None, both the starting and ending tag are mandatory.</td> </tr> <tr> <th scope="row">Permitted parents</th> <td> Any element that accepts <a href="../content_categories#flow_content">flow content</a> </td> </tr> <tr> <th scope="row">Implicit ARIA role</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role">dialog</a></td> </tr> <tr> <th scope="row">Permitted ARIA roles</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role"><code>alertdialog</code></a></td> </tr> <tr> <th scope="row">DOM interface</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement"><code>HTMLDialogElement</code></a></td> </tr> </tbody> </table></div></figure></div> +<h2 id="accessibility_considerations">Accessibility considerations</h2> +<div class="section-content"> +<p>When implementing a dialog, it is important to consider the most appropriate place to set user focus. When using <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal"><code>HTMLDialogElement.showModal()</code></a> to open a <code><dialog></code>, focus is set on the first nested focusable element. Explicitly indicating the initial focus placement by using the <a href="../global_attributes/autofocus"><code>autofocus</code></a> attribute will help ensure initial focus is set on the element deemed the best initial focus placement for any particular dialog. When in doubt, as it may not always be known where initial focus could be set within a dialog, particularly for instances where a dialog's content is dynamically rendered when invoked, the <code><dialog></code> element itself may provide the best initial focus placement.</p> <p>Ensure a mechanism is provided to allow users to close the dialog. The most robust way to ensure that all users can close the dialog is to include an explicit button to do so, such as a confirmation, cancellation, or close button.</p> <p>By default, a dialog invoked by the <code>showModal()</code> method can be dismissed by pressing the <kbd>Esc</kbd> key. A non-modal dialog does not dismiss via the <kbd>Esc</kbd> key by default, and depending on what the non-modal dialog represents, it may not be desired for this behavior. Keyboard users expect the <kbd>Esc</kbd> key to close modal dialogs; ensure that this behavior is implemented and maintained. If multiple modal dialogs are open, pressing the <kbd>Esc</kbd> key should close only the last shown dialog. When using <code><dialog></code>, this behavior is provided by the browser.</p> <p>While dialogs can be created using other elements, the native <code><dialog></code> element provides usability and accessibility features that must be replicated if you use other elements for a similar purpose. If you're creating a custom dialog implementation, ensure that all expected default behaviors are supported and proper labeling recommendations are followed.</p> <p>The <code><dialog></code> element is exposed by browsers in a manner similar to custom dialogs that use the ARIA <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role">role="dialog"</a> attribute. <code><dialog></code> elements invoked by the <code>showModal()</code> method implicitly have <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal">aria-modal="true"</a>, whereas <code><dialog></code> elements invoked by the <code>show()</code> method or displayed using the <code>open</code> attribute or by changing the default <code>display</code> of a <code><dialog></code> are exposed as <code>[aria-modal="false"]</code>. When implementing modal dialogs, everything other than the <code><dialog></code> and its contents should be rendered inert using the <a href="../global_attributes/inert"><code>inert</code></a> attribute. When using <code><dialog></code> along with the <code>HTMLDialogElement.showModal()</code> method, this behavior is provided by the browser.</p> +</div> +<h2 id="specifications">Specifications</h2> +<div class="_table"><table class="standard-table"> +<thead><tr><th scope="col">Specification</th></tr></thead> +<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element">HTML Standard <br><small># the-dialog-element</small></a></td></tr></tbody> +</table></div> +<h2 id="browser_compatibility">Browser compatibility</h2> +<div class="_table"><table> +<thead> +<tr id="bct-browser-type"> +<th></th> +<th colspan="6">Desktop</th> +<th colspan="6">Mobile</th> +</tr> +<tr id="bct-browsers"> +<th></th> +<th>Chrome</th> +<th>Edge</th> +<th>Firefox</th> +<th>Internet Explorer</th> +<th>Opera</th> +<th>Safari</th> +<th>WebView Android</th> +<th>Chrome Android</th> +<th>Firefox for Android</th> +<th>Opera Android</th> +<th>Safari on IOS</th> +<th>Samsung Internet</th> +</tr> +</thead> +<tbody> +<tr> +<th><code>dialog</code></th> +<td class="bc-supports-yes">37</td> +<td class="bc-supports-yes">79</td> +<td class="bc-supports-yes">98</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">24</td> +<td class="bc-supports-yes">15.4</td> +<td class="bc-supports-yes">37</td> +<td class="bc-supports-yes">37</td> +<td class="bc-supports-yes">98</td> +<td class="bc-supports-yes">24</td> +<td class="bc-supports-yes">15.4</td> +<td class="bc-supports-yes">3.0</td> +</tr> +<tr> +<th><code>open</code></th> +<td class="bc-supports-yes">37</td> +<td class="bc-supports-yes">79</td> +<td class="bc-supports-yes">98</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">24</td> +<td class="bc-supports-yes">15.4</td> +<td class="bc-supports-yes">37</td> +<td class="bc-supports-yes">37</td> +<td class="bc-supports-yes">98</td> +<td class="bc-supports-yes">24</td> +<td class="bc-supports-yes">15.4</td> +<td class="bc-supports-yes">3.0</td> +</tr> +</tbody> +</table></div> +<h2 id="see_also">See also</h2> +<div class="section-content"><ul> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement"><code>HTMLDialogElement</code></a> interface</li> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close_event"><code>close</code></a> event</li> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/cancel_event"><code>cancel</code></a> event</li> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/open"><code>open</code></a> property of the <code>HTMLDialogElement</code> interface</li> <li> +<a href="../global_attributes/inert"><code>inert</code></a> global attribute for HTML elements</li> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/::backdrop"><code>::backdrop</code></a> CSS pseudo-element</li> <li> +<a href="https://developer.mozilla.org/en-US/docs/Learn/Forms">Web forms</a> in the Learn area</li> </ul></div><div class="_attribution"> + <p class="_attribution-p"> + © 2005–2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br> + <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog</a> + </p> +</div> |