From ceff1d9dbaa8034339721870b3d15631a4f4ab5c Mon Sep 17 00:00:00 2001 From: Leevi Graham Date: Wed, 26 Nov 2025 22:46:29 +1100 Subject: [PATCH 1/7] Revise: Web APIs / HTMLDialogElement * Rewrote html / javascript examples for consistency * Added examples of `returnValue` in close and requestClose * Added additional context around close requests, cancel events --- .../htmldialogelement/cancel_event/index.md | 73 ++++++++------- .../web/api/htmldialogelement/close/index.md | 80 +++++++---------- .../api/htmldialogelement/closedby/index.md | 17 ++-- .../web/api/htmldialogelement/open/index.md | 3 +- .../htmldialogelement/requestclose/index.md | 90 +++++++++---------- .../htmldialogelement/returnvalue/index.md | 6 +- .../web/api/htmldialogelement/show/index.md | 61 +++---------- .../api/htmldialogelement/showmodal/index.md | 57 ++++-------- 8 files changed, 164 insertions(+), 223 deletions(-) diff --git a/files/en-us/web/api/htmldialogelement/cancel_event/index.md b/files/en-us/web/api/htmldialogelement/cancel_event/index.md index 75fb3a7fd8342f8..65a22d7dd95f38f 100644 --- a/files/en-us/web/api/htmldialogelement/cancel_event/index.md +++ b/files/en-us/web/api/htmldialogelement/cancel_event/index.md @@ -8,11 +8,15 @@ browser-compat: api.HTMLDialogElement.cancel_event {{APIRef("HTML DOM")}} -The **`cancel`** event fires on a {{HTMLElement("dialog")}} element when the user instructs the browser that they wish to dismiss the current open dialog. The browser fires this event when the user presses the Esc key. +The **`cancel`** event fires on a {{HTMLElement("dialog")}} element when the user sends a [close request](https://html.spec.whatwg.org/multipage/interaction.html#close-request) to the user agent. -This event is cancelable but can not bubble. +Examples of close requests are: + +- Pressing the ESC key on desktop platforms +- Calling the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method. +- The back button on mobile platforms -When a `` is dismissed with the Esc key, both the `cancel` and {{domxref("HTMLDialogElement/close_event", "close")}} events are fired. +This event is cancelable but can not bubble. ## Syntax @@ -32,49 +36,56 @@ A generic {{domxref("Event")}}. ### Canceling a dialog +The following example shows a button that, when clicked, opens a {{htmlelement("dialog")}} via the {{domxref("HTMLDialogElement.showModal()", "showModal()")}} method. + +From there you can will trigger the `cancel` event by either clicking _Request Close_ button to close the dialog (via the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method) or press the ESC key. + +Preventing the dialog from closing is demonstrated with a checkbox. + #### HTML ```html - - + +
+ +
+ - + -
+

``` -```css hidden -button, -div { - margin: 0.5rem; -} -``` - -#### JavaScript - ```js -const result = document.querySelector(".result"); - -const dialog = document.querySelector(".example-dialog"); +const dialog = document.getElementById("dialog"); +const openButton = document.getElementById("open"); +const requestCloseButton = document.getElementById("requestClose"); +const preventCloseInput = document.getElementById("preventClose"); +const statusText = document.getElementById("statusText"); + +// Update button opens a modal dialog +openButton.addEventListener("click", () => { + dialog.showModal(); +}); -dialog.addEventListener("cancel", (event) => { - result.textContent = "dialog was canceled"; +// Request close +requestCloseButton.addEventListener("click", () => { + // Triggers the cancel event + dialog.requestClose(); }); -const openDialog = document.querySelector(".open-dialog"); -openDialog.addEventListener("click", () => { - if (typeof dialog.showModal === "function") { - dialog.showModal(); - result.textContent = ""; - } else { - result.textContent = "The dialog API is not supported by this browser"; +// Fired when requestClose() is called +// Prevent the dialog from closing by calling event.preventDefault() +dialog.addEventListener("cancel", (event) => { + if (preventClose.checked) { + statusText.innerText = "Dialog close cancelled"; + event.preventDefault(); } }); -const closeButton = document.querySelector(".close"); -closeButton.addEventListener("click", () => { - dialog.close(); +dialog.addEventListener("close", (event) => { + statusText.innerText = "Dialog closed"; }); ``` diff --git a/files/en-us/web/api/htmldialogelement/close/index.md b/files/en-us/web/api/htmldialogelement/close/index.md index 800d511128b4da1..23919dd27bb8e4a 100644 --- a/files/en-us/web/api/htmldialogelement/close/index.md +++ b/files/en-us/web/api/htmldialogelement/close/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLDialogElement.close {{ APIRef("HTML DOM") }} The **`close()`** method of the {{domxref("HTMLDialogElement")}} interface closes the {{htmlelement("dialog")}}. -An optional string may be passed as an argument, updating the `returnValue` of the dialog. +An optional string may be passed as an argument, updating the {{domxref("HTMLDialogElement.returnValue", "returnValue")}} of the dialog. ## Syntax @@ -29,68 +29,56 @@ None ({{jsxref("undefined")}}). ## Examples -The following example shows a simple button that, when clicked, opens a {{htmlelement("dialog")}} containing a form via the `showModal()` method. -From there you can click the _X_ button to close the dialog (via the `HTMLDialogElement.close()` method), or submit the form via the submit button. +The following example shows a button that, when clicked, opens a {{htmlelement("dialog")}} via the {{domxref("HTMLDialogElement.showModal()", "showModal()")}} method. +From there you can click the either _Close_ button to close the dialog (via the `close()` method). + +The _Close_ button closes the dialog without a {{domxref("HTMLDialogElement.returnValue", "returnValue")}}, while the _Close w/ return value_ button closes the dialog with a {{domxref("HTMLDialogElement.returnValue", "returnValue")}}. ```html - - -
- -
-

- - -

-
- -
  • - -
    • -
  • - -
    • -     -
    + + + - + + +

    ``` ```js -const updateButton = document.getElementById("updateDetails"); +const dialog = document.getElementById("dialog"); +const openButton = document.getElementById("open"); const closeButton = document.getElementById("close"); -const dialog = document.getElementById("favDialog"); -dialog.returnValue = "favAnimal"; - -function openCheck(dialog) { - if (dialog.open) { - console.log("Dialog open"); - } else { - console.log("Dialog closed"); - } -} +const closeWithValueButton = document.getElementById("closeWithValue"); +const statusText = document.getElementById("statusText"); // Update button opens a modal dialog -updateButton.addEventListener("click", () => { +openButton.addEventListener("click", () => { + // Reset the return value + dialog.returnValue = ""; + // Rhow the dialog dialog.showModal(); - openCheck(dialog); }); -// Form close button closes the dialog box +// Close button closes the dialog box closeButton.addEventListener("click", () => { - dialog.close("animalNotChosen"); - openCheck(dialog); + dialog.close(); +}); + +// Close button closes the dialog box with a return value +closeWithReturnValueButton.addEventListener("click", () => { + dialog.close("some value"); +}); + +// Form close button closes the dialog box +dialog.addEventListener("close", () => { + statusText.innerHTML = `Dialog closed. Return value: "${dialog.returnValue}"`; }); ``` -If the "X" button was of `type="submit"`, the dialog would have closed without requiring JavaScript. -A form submission closes the `` it is nested within if the [form's method is `dialog`](/en-US/docs/Web/HTML/Reference/Elements/form#method), so no "close" button is required. +> [!NOTE] +> +> You know you can also automatically close a `` by submitting a {{htmlelement("form")}} element with a [`method="dialog"`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attribute. ### Result diff --git a/files/en-us/web/api/htmldialogelement/closedby/index.md b/files/en-us/web/api/htmldialogelement/closedby/index.md index 2b5bff0ae1a6a72..c4aeb2b0bb9fe4e 100644 --- a/files/en-us/web/api/htmldialogelement/closedby/index.md +++ b/files/en-us/web/api/htmldialogelement/closedby/index.md @@ -16,11 +16,18 @@ The **`closedBy`** property of the A string; possible values are: - `any` - - : The dialog can be dismissed with a light dismiss user action, a platform-specific user action, or a developer-specified mechanism. + - : The dialog can be dismissed by a [close request](https://html.spec.whatwg.org/multipage/interaction.html#close-request) or clicks outside the dialog. - `closerequest` - - : The dialog can be dismissed with a platform-specific user action or a developer-specified mechanism. + - : The dialog can only be dismissed by a [close request](https://html.spec.whatwg.org/multipage/interaction.html#close-request). - `none` - - : The dialog can only be dismissed with a developer-specified mechanism. + - : No user actions automatically close the dialog. The dialog can only be dismissed with a developer-specified mechanism. + +### Default behaviour + +If the `closedby` attribute is absent or invalid, it falls back to the **Auto** state. In the **Auto** state: + +- when the `` is opened with `showModal()`, it behaves as if: `closedby="closerequest"` +- when the `` is opened by any other means, it behaves as if: `closedby="none"` ## Examples @@ -30,8 +37,8 @@ A string; possible values are:

    My dialog

    - Closable using the Esc key, or by clicking outside the dialog. "Light - dismiss" behavior. + Closable using the ESC key, or by clicking outside the dialog. + "Light dismiss" behavior.

    ``` diff --git a/files/en-us/web/api/htmldialogelement/open/index.md b/files/en-us/web/api/htmldialogelement/open/index.md index b805d18da10e5e3..6de14aa02e9c7cd 100644 --- a/files/en-us/web/api/htmldialogelement/open/index.md +++ b/files/en-us/web/api/htmldialogelement/open/index.md @@ -39,7 +39,8 @@ button.

    -

    + +

    Dialog closed

    ``` ```js diff --git a/files/en-us/web/api/htmldialogelement/requestclose/index.md b/files/en-us/web/api/htmldialogelement/requestclose/index.md index e6b060a3f4e9d4b..f224770325f39a0 100644 --- a/files/en-us/web/api/htmldialogelement/requestclose/index.md +++ b/files/en-us/web/api/htmldialogelement/requestclose/index.md @@ -9,10 +9,10 @@ browser-compat: api.HTMLDialogElement.requestClose {{ APIRef("HTML DOM") }} The **`requestClose()`** method of the {{domxref("HTMLDialogElement")}} interface requests to close the {{htmlelement("dialog")}}. -An optional string may be passed as an argument, updating the `returnValue` of the dialog. +An optional string may be passed as an argument, updating the {{domxref("HTMLDialogElement.returnValue", "returnValue")}} of the dialog. -This method differs from the {{domxref("HTMLDialogElement.close()")}} method in that it fires a {{domxref("HTMLDialogElement.cancel_event", "cancel")}} event before firing the {{domxref("HTMLDialogElement.close_event", "close")}} event. -Authors can call {{domxref("Event.preventDefault()")}} in the handler for the `cancel` event to prevent the dialog from closing. +This method differs from the {{domxref("HTMLDialogElement.close()", "close()")}} method in that it fires a {{domxref("HTMLDialogElement.cancel_event", "cancel")}} event before firing the {{domxref("HTMLDialogElement.close_event", "close")}} event. +Authors can call {{domxref("Event.preventDefault()")}} in the handler for the {{domxref("HTMLDialogElement.cancel_event", "cancel")}} event to prevent the dialog from closing. This method exposes the same behavior as the dialog's internal close watcher. @@ -36,75 +36,69 @@ None ({{jsxref("undefined")}}). ### Using requestClose() -The following example shows a simple button that, when clicked, opens a {{htmlelement("dialog")}} containing a form, via the `showModal()` method. -Once open you can click the **X** button to request to close the dialog (via the `HTMLDialogElement.requestClose()` method), or submit the form via the **Confirm** button. +The following example shows a button that, when clicked, opens a {{htmlelement("dialog")}} via the {{domxref("HTMLDialogElement.showModal()", "showModal()")}} method. +From there you can click the either _Close_ button to close the dialog (via the `requestClose()` method). + +The _Close_ button closes the dialog without a {{domxref("HTMLDialogElement.returnValue", "returnValue")}}, while the _Close w/ return value_ button closes the dialog with a {{domxref("HTMLDialogElement.returnValue", "returnValue")}}. + +Preventing the dialog from closing is demonstrated with a checkbox. #### HTML ```html - - -
    - -
    -

    - - -

    -
    - -
  • - -
    • -
  • - -
    • -     -
    + +
    + +
    + +     - -``` + -#### JavaScript +

    +``` ```js -const updateButton = document.getElementById("updateDetails"); +const dialog = document.getElementById("dialog"); +const openButton = document.getElementById("open"); const closeButton = document.getElementById("close"); -const dialog = document.getElementById("favDialog"); +const closeWithValueButton = document.getElementById("closeWithValue"); +const preventCloseInput = document.getElementById("preventClose"); +const statusText = document.getElementById("statusText"); // Update button opens a modal dialog -updateButton.addEventListener("click", () => { +openButton.addEventListener("click", () => { + // Reset the return value + dialog.returnValue = ""; + // Show the dialog dialog.showModal(); }); -// Form close button requests to close the dialog box +// Close button closes the dialog box closeButton.addEventListener("click", () => { - dialog.requestClose("animalNotChosen"); + dialog.requestClose(); }); -function dialogShouldNotClose() { - // Add logic to decide whether to allow the dialog to close. - // Closing prevented by default - return true; -} +// Close button closes the dialog box with a return value +closeWithValueButton.addEventListener("click", () => { + dialog.requestClose("some value"); +}); +// Fired when requestClose() is called +// Prevent the dialog from closing by calling event.preventDefault() dialog.addEventListener("cancel", (event) => { - if (!event.cancelable) return; - if (dialogShouldNotClose()) { - console.log("Closing prevented"); + if (cancelCloseInput.checked) { + statusText.innerText = "Dialog close cancelled"; event.preventDefault(); } }); -``` -If the "X" button was of `type="submit"`, the dialog would have closed without requiring JavaScript. -A form submission closes the `` it is nested within if the [form's method is `dialog`](/en-US/docs/Web/HTML/Reference/Elements/form#method), so no "close" button is required. +// cancel event is not prevented, dialog will close +dialog.addEventListener("close", () => { + statusText.innerHTML = `Dialog closed. Return value: "${dialog.returnValue}"`; +}); +``` #### Result diff --git a/files/en-us/web/api/htmldialogelement/returnvalue/index.md b/files/en-us/web/api/htmldialogelement/returnvalue/index.md index 69d838d09f9362f..d6b630cd480ca6b 100644 --- a/files/en-us/web/api/htmldialogelement/returnvalue/index.md +++ b/files/en-us/web/api/htmldialogelement/returnvalue/index.md @@ -56,14 +56,14 @@ openDialogButton.addEventListener("click", () => { dialog.showModal(); }); -declineButton.addEventListener("click", closeDialog); -acceptButton.addEventListener("click", closeDialog); - function closeDialog(event) { const button = event.target; dialog.close(button.value); } +declineButton.addEventListener("click", closeDialog); +acceptButton.addEventListener("click", closeDialog); + dialog.addEventListener("close", () => { statusText.innerText = dialog.returnValue ? `Return value: ${dialog.returnValue}` diff --git a/files/en-us/web/api/htmldialogelement/show/index.md b/files/en-us/web/api/htmldialogelement/show/index.md index 457861539ed8423..0dd7a9b5b740885 100644 --- a/files/en-us/web/api/htmldialogelement/show/index.md +++ b/files/en-us/web/api/htmldialogelement/show/index.md @@ -33,67 +33,34 @@ None ({{jsxref("undefined")}}). ### Basic usage -The following example shows a simple button that, when clicked, opens a {{htmlelement("dialog")}} containing a form via the `show()` method. -From there you can click the _Cancel_ button ("X") to close the dialog (via the {{domxref("HTMLDialogElement.close()")}} method), or submit the form via the submit button. +The following example shows a simple button that, when clicked, opens a {{htmlelement("dialog")}} via the `show()` method. +From there you can click the _Close dialog_ button to close the dialog (via the {{domxref("HTMLDialogElement.close()", "close()")}} method). #### HTML ```html - - -
    - -
    -

    - - -

    -
    - -
  • - -
    • -
  • - -
    • -     -
    + + - + ``` #### 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 cancelled"); - } -} - -// Update button opens a modeless dialog -updateButton.addEventListener("click", () => { +const openButton = document.getElementById("open"); +const closeButton = document.getElementById("close"); +const dialog = document.getElementById("dialog"); + +// Open button opens a modeless dialog +openButton.addEventListener("click", () => { dialog.show(); - openCheck(dialog); }); -// Form cancel button closes the dialog box -cancelButton.addEventListener("click", () => { - dialog.close("animalNotChosen"); - openCheck(dialog); +// Close button closes the dialog box +closeButton.addEventListener("click", () => { + dialog.close(); }); ``` diff --git a/files/en-us/web/api/htmldialogelement/showmodal/index.md b/files/en-us/web/api/htmldialogelement/showmodal/index.md index 08c808c5c48c7a3..4ebef1a3da9fdd3 100644 --- a/files/en-us/web/api/htmldialogelement/showmodal/index.md +++ b/files/en-us/web/api/htmldialogelement/showmodal/index.md @@ -34,63 +34,36 @@ None ({{jsxref("undefined")}}). ## Examples -### Opening a modal dialog +### Basic usage -The following example shows a button that, when clicked, opens a modal {{htmlelement("dialog")}} containing a form via the `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("HTMLDialogElement/cancel_event", "cancel")}} event. +The following example shows a simple button that, when clicked, opens a {{htmlelement("dialog")}} via the `showModal()` method. +From there you can click the _Close dialog_ button to close the dialog (via the {{domxref("HTMLDialogElement.close()")}} method). #### HTML ```html - - -
    -

    - - -

    -
    - - -
    -
    + + -
    - -
    + ``` #### 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", () => { +const openButton = document.getElementById("open"); +const closeButton = document.getElementById("close"); +const dialog = document.getElementById("dialog"); + +// Open button opens a modeless dialog +openButton.addEventListener("click", () => { dialog.showModal(); - openCheck(dialog); }); -// Form cancel button closes the dialog box -cancelButton.addEventListener("click", () => { - dialog.close("animalNotChosen"); - openCheck(dialog); +// Close button closes the dialog box +closeButton.addEventListener("click", () => { + dialog.close(); }); ``` From 27000860ff77e2fe69cff707d8ae3ad12bbddfb3 Mon Sep 17 00:00:00 2001 From: Leevi Graham Date: Thu, 27 Nov 2025 08:44:41 +1100 Subject: [PATCH 2/7] Updated examples --- .../htmldialogelement/cancel_event/index.md | 12 +++--- .../web/api/htmldialogelement/close/index.md | 8 ++-- .../htmldialogelement/close_event/index.md | 20 ++++----- .../api/htmldialogelement/closedby/index.md | 2 +- .../web/api/htmldialogelement/open/index.md | 17 +++----- .../htmldialogelement/requestclose/index.md | 12 +++--- .../htmldialogelement/returnvalue/index.md | 41 ++++++++++--------- .../web/api/htmldialogelement/show/index.md | 2 +- .../api/htmldialogelement/showmodal/index.md | 2 +- 9 files changed, 56 insertions(+), 60 deletions(-) diff --git a/files/en-us/web/api/htmldialogelement/cancel_event/index.md b/files/en-us/web/api/htmldialogelement/cancel_event/index.md index 65a22d7dd95f38f..06c2e457870c6b2 100644 --- a/files/en-us/web/api/htmldialogelement/cancel_event/index.md +++ b/files/en-us/web/api/htmldialogelement/cancel_event/index.md @@ -47,22 +47,22 @@ Preventing the dialog from closing is demonstrated with a checkbox. ```html
    - +
    - +     -

    +

    ``` ```js const dialog = document.getElementById("dialog"); const openButton = document.getElementById("open"); -const requestCloseButton = document.getElementById("requestClose"); -const preventCloseInput = document.getElementById("preventClose"); -const statusText = document.getElementById("statusText"); +const requestCloseButton = document.getElementById("request-close"); +const preventCloseInput = document.getElementById("prevent-close"); +const statusText = document.getElementById("status-text"); // Update button opens a modal dialog openButton.addEventListener("click", () => { diff --git a/files/en-us/web/api/htmldialogelement/close/index.md b/files/en-us/web/api/htmldialogelement/close/index.md index 23919dd27bb8e4a..3067b3cf0c6cc65 100644 --- a/files/en-us/web/api/htmldialogelement/close/index.md +++ b/files/en-us/web/api/htmldialogelement/close/index.md @@ -37,20 +37,20 @@ The _Close_ button closes the dialog without a {{domxref("HTMLDialogElement.retu ```html - + -

    +

    ``` ```js const dialog = document.getElementById("dialog"); const openButton = document.getElementById("open"); const closeButton = document.getElementById("close"); -const closeWithValueButton = document.getElementById("closeWithValue"); -const statusText = document.getElementById("statusText"); +const closeWithValueButton = document.getElementById("close-w-value"); +const statusText = document.getElementById("status-text"); // Update button opens a modal dialog openButton.addEventListener("click", () => { diff --git a/files/en-us/web/api/htmldialogelement/close_event/index.md b/files/en-us/web/api/htmldialogelement/close_event/index.md index 13a91985573a4cd..5c5aaa7097241f4 100644 --- a/files/en-us/web/api/htmldialogelement/close_event/index.md +++ b/files/en-us/web/api/htmldialogelement/close_event/index.md @@ -33,17 +33,17 @@ A generic {{domxref("Event")}}. #### HTML ```html - +
    - +

    Or hit the Esc key

     -
    +
    ``` ```css hidden @@ -56,20 +56,20 @@ div { #### JavaScript ```js -const result = document.querySelector(".result"); +const dialog = document.getElementById("dialog"); +const openButton = document.getElementById("open"); +const closeButton = document.getElementById("close"); +const statusText = document.getElementById("status-text"); -const dialog = document.querySelector(".example-dialog"); dialog.addEventListener("close", (event) => { - result.textContent = "dialog was closed"; + statusText.textContent = "dialog was closed"; }); -const openDialog = document.querySelector(".open-dialog"); -openDialog.addEventListener("click", () => { +openButton.addEventListener("click", () => { dialog.showModal(); - result.textContent = ""; + statusText.textContent = ""; }); -const closeButton = document.querySelector(".close"); closeButton.addEventListener("click", () => { dialog.close(); }); diff --git a/files/en-us/web/api/htmldialogelement/closedby/index.md b/files/en-us/web/api/htmldialogelement/closedby/index.md index c4aeb2b0bb9fe4e..9ba1ccc78e969fb 100644 --- a/files/en-us/web/api/htmldialogelement/closedby/index.md +++ b/files/en-us/web/api/htmldialogelement/closedby/index.md @@ -44,7 +44,7 @@ If the `closedby` attribute is absent or invalid, it falls back to the **Auto** ``` ```js -const dialogElem = document.querySelector("dialog"); +const dialog = document.querySelector("dialog"); // Logs "any" to the console console.log(dialogElem.closedBy); diff --git a/files/en-us/web/api/htmldialogelement/open/index.md b/files/en-us/web/api/htmldialogelement/open/index.md index 6de14aa02e9c7cd..89d648128b560e2 100644 --- a/files/en-us/web/api/htmldialogelement/open/index.md +++ b/files/en-us/web/api/htmldialogelement/open/index.md @@ -37,27 +37,22 @@ button.

    - +

    -

    Dialog closed

    +

    Dialog closed

    ``` ```js -const openDialog = document.getElementById("openDialog"); const dialog = document.getElementById("dialog"); -const text = document.getElementById("dialogStatus"); +const openButton = document.getElementById("open"); +const statusText = document.getElementById("status-text"); function openCheck(dialog) { - if (dialog.open) { - text.innerText = "Dialog open"; - } else { - text.innerText = "Dialog closed"; - } + statusText.innerText = dialog.open ? "Dialog open" : "Dialog closed"; } -// Update button opens a modal dialog -openDialog.addEventListener("click", () => { +openButton.addEventListener("click", () => { dialog.showModal(); openCheck(dialog); }); diff --git a/files/en-us/web/api/htmldialogelement/requestclose/index.md b/files/en-us/web/api/htmldialogelement/requestclose/index.md index f224770325f39a0..013666dee52f40e 100644 --- a/files/en-us/web/api/htmldialogelement/requestclose/index.md +++ b/files/en-us/web/api/htmldialogelement/requestclose/index.md @@ -48,24 +48,24 @@ Preventing the dialog from closing is demonstrated with a checkbox. ```html
    - +
    - +     -

    +

    ``` ```js const dialog = document.getElementById("dialog"); const openButton = document.getElementById("open"); const closeButton = document.getElementById("close"); -const closeWithValueButton = document.getElementById("closeWithValue"); -const preventCloseInput = document.getElementById("preventClose"); -const statusText = document.getElementById("statusText"); +const closeWithValueButton = document.getElementById("close-w-value"); +const preventCloseInput = document.getElementById("prevent-close"); +const statusText = document.getElementById("status-text"); // Update button opens a modal dialog openButton.addEventListener("click", () => { diff --git a/files/en-us/web/api/htmldialogelement/returnvalue/index.md b/files/en-us/web/api/htmldialogelement/returnvalue/index.md index d6b630cd480ca6b..94f079a82f49cc7 100644 --- a/files/en-us/web/api/htmldialogelement/returnvalue/index.md +++ b/files/en-us/web/api/htmldialogelement/returnvalue/index.md @@ -31,28 +31,29 @@ If the user dismisses the dialog without clicking a button (for example, by pres #### HTML ```html - +

    Do you agree to the Terms of Service (link)?

    - - + +     -

    - -

    -

    + +

    ``` #### JavaScript ```js -const dialog = document.getElementById("termsDialog"); -const statusText = document.getElementById("statusText"); - -const openDialogButton = document.getElementById("openDialogButton"); -const declineButton = document.getElementById("declineButton"); -const acceptButton = document.getElementById("acceptButton"); - -openDialogButton.addEventListener("click", () => { +const dialog = document.getElementById("dialog"); +const openButton = document.getElementById("open"); +const declineButton = document.getElementById("decline"); +const acceptButton = document.getElementById("accept"); +const statusText = document.getElementById("status-text"); + +openButton.addEventListener("click", () => { + // Reset the return value on each open + dialog.returnValue = ""; + updateReturnValue(); + // Show the dialog dialog.showModal(); }); @@ -61,14 +62,14 @@ function closeDialog(event) { dialog.close(button.value); } +function updateReturnValue() { + statusText.innerHTML = `Return value: "${dialog.returnValue}"`; +} + declineButton.addEventListener("click", closeDialog); acceptButton.addEventListener("click", closeDialog); -dialog.addEventListener("close", () => { - statusText.innerText = dialog.returnValue - ? `Return value: ${dialog.returnValue}` - : "There was no return value"; -}); +dialog.addEventListener("close", () => updateReturnValue()); ``` #### Result diff --git a/files/en-us/web/api/htmldialogelement/show/index.md b/files/en-us/web/api/htmldialogelement/show/index.md index 0dd7a9b5b740885..b2b5f5ae6e28374 100644 --- a/files/en-us/web/api/htmldialogelement/show/index.md +++ b/files/en-us/web/api/htmldialogelement/show/index.md @@ -49,9 +49,9 @@ From there you can click the _Close dialog_ button to close the dialog (via the #### JavaScript ```js +const dialog = document.getElementById("dialog"); const openButton = document.getElementById("open"); const closeButton = document.getElementById("close"); -const dialog = document.getElementById("dialog"); // Open button opens a modeless dialog openButton.addEventListener("click", () => { diff --git a/files/en-us/web/api/htmldialogelement/showmodal/index.md b/files/en-us/web/api/htmldialogelement/showmodal/index.md index 4ebef1a3da9fdd3..f7bfbc36ad7e2f6 100644 --- a/files/en-us/web/api/htmldialogelement/showmodal/index.md +++ b/files/en-us/web/api/htmldialogelement/showmodal/index.md @@ -52,9 +52,9 @@ From there you can click the _Close dialog_ button to close the dialog (via the #### JavaScript ```js +const dialog = document.getElementById("dialog"); const openButton = document.getElementById("open"); const closeButton = document.getElementById("close"); -const dialog = document.getElementById("dialog"); // Open button opens a modeless dialog openButton.addEventListener("click", () => { From f1e0188cacea5c9a9ef20bc9248f55609c4a64f0 Mon Sep 17 00:00:00 2001 From: Leevi Graham Date: Thu, 27 Nov 2025 08:49:31 +1100 Subject: [PATCH 3/7] inline function call for consistency with previous lines --- files/en-us/web/api/htmldialogelement/returnvalue/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/htmldialogelement/returnvalue/index.md b/files/en-us/web/api/htmldialogelement/returnvalue/index.md index 94f079a82f49cc7..d5cae56233f3685 100644 --- a/files/en-us/web/api/htmldialogelement/returnvalue/index.md +++ b/files/en-us/web/api/htmldialogelement/returnvalue/index.md @@ -69,7 +69,7 @@ function updateReturnValue() { declineButton.addEventListener("click", closeDialog); acceptButton.addEventListener("click", closeDialog); -dialog.addEventListener("close", () => updateReturnValue()); +dialog.addEventListener("close", updateReturnValue); ``` #### Result From d330ecc71a057df5820aef66c65317a3a19d3569 Mon Sep 17 00:00:00 2001 From: Leevi Graham Date: Thu, 27 Nov 2025 17:20:54 +1100 Subject: [PATCH 4/7] Revise index, add consistent logging to examples --- .../htmldialogelement/cancel_event/index.md | 34 ++++- .../web/api/htmldialogelement/close/index.md | 26 +++- .../htmldialogelement/close_event/index.md | 35 +++-- .../api/htmldialogelement/closedby/index.md | 2 +- .../en-us/web/api/htmldialogelement/index.md | 141 ++++++++++-------- .../web/api/htmldialogelement/open/index.md | 30 +++- .../htmldialogelement/requestclose/index.md | 28 +++- .../htmldialogelement/returnvalue/index.md | 29 +++- .../api/htmldialogelement/showmodal/index.md | 2 +- .../htmlelement/beforetoggle_event/index.md | 2 +- .../web/api/htmlelement/toggle_event/index.md | 2 +- 11 files changed, 223 insertions(+), 108 deletions(-) diff --git a/files/en-us/web/api/htmldialogelement/cancel_event/index.md b/files/en-us/web/api/htmldialogelement/cancel_event/index.md index 06c2e457870c6b2..37622f7fa4c0824 100644 --- a/files/en-us/web/api/htmldialogelement/cancel_event/index.md +++ b/files/en-us/web/api/htmldialogelement/cancel_event/index.md @@ -12,7 +12,7 @@ The **`cancel`** event fires on a {{HTMLElement("dialog")}} element when the use Examples of close requests are: -- Pressing the ESC key on desktop platforms +- Pressing the Esc key on desktop platforms - Calling the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method. - The back button on mobile platforms @@ -38,7 +38,7 @@ A generic {{domxref("Event")}}. The following example shows a button that, when clicked, opens a {{htmlelement("dialog")}} via the {{domxref("HTMLDialogElement.showModal()", "showModal()")}} method. -From there you can will trigger the `cancel` event by either clicking _Request Close_ button to close the dialog (via the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method) or press the ESC key. +From there you can will trigger the `cancel` event by either clicking _Request Close_ button to close the dialog (via the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method) or press the Esc key. Preventing the dialog from closing is demonstrated with a checkbox. @@ -53,8 +53,27 @@ Preventing the dialog from closing is demonstrated with a checkbox.     +``` + +```html hidden +
    
+```
 
-
    
+```css hidden
+#status-text {
+  height: 120px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const statusText = document.getElementById("status-text");
+function log(text) {
+  statusText.innerText = `${statusText.innerText}${text}\n`;
+  statusText.scrollTop = statusText.scrollHeight;
+}
 ```
 
 ```js
@@ -62,7 +81,6 @@ const dialog = document.getElementById("dialog");
 const openButton = document.getElementById("open");
 const requestCloseButton = document.getElementById("request-close");
 const preventCloseInput = document.getElementById("prevent-close");
-const statusText = document.getElementById("status-text");
 
 // Update button opens a modal dialog
 openButton.addEventListener("click", () => {
@@ -78,20 +96,20 @@ requestCloseButton.addEventListener("click", () => {
 // Fired when requestClose() is called
 // Prevent the dialog from closing by calling event.preventDefault()
 dialog.addEventListener("cancel", (event) => {
-  if (preventClose.checked) {
-    statusText.innerText = "Dialog close cancelled";
+  if (preventCloseInput.checked) {
+    log("Dialog close cancelled");
     event.preventDefault();
   }
 });
 
 dialog.addEventListener("close", (event) => {
-  statusText.innerText = "Dialog closed";
+  log("Dialog closed");
 });
 ```
 
 #### Result
 
-{{ EmbedLiveSample('Canceling a dialog', '100%', '100px') }}
+{{ EmbedLiveSample('Canceling a dialog', '100%', '250px') }}
 
 ## Specifications
 
diff --git a/files/en-us/web/api/htmldialogelement/close/index.md b/files/en-us/web/api/htmldialogelement/close/index.md
index 3067b3cf0c6cc65..e7fd2b537388a36 100644
--- a/files/en-us/web/api/htmldialogelement/close/index.md
+++ b/files/en-us/web/api/htmldialogelement/close/index.md
@@ -41,8 +41,27 @@ The _Close_ button closes the dialog without a {{domxref("HTMLDialogElement.retu
     
 
 
+```
+
+```html hidden
+
    
+```
 
-
    
+```css hidden
+#status-text {
+  height: 120px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const statusText = document.getElementById("status-text");
+function log(text) {
+  statusText.innerText = `${statusText.innerText}${text}\n`;
+  statusText.scrollTop = statusText.scrollHeight;
+}
 ```
 
 ```js
@@ -50,7 +69,6 @@ const dialog = document.getElementById("dialog");
 const openButton = document.getElementById("open");
 const closeButton = document.getElementById("close");
 const closeWithValueButton = document.getElementById("close-w-value");
-const statusText = document.getElementById("status-text");
 
 // Update button opens a modal dialog
 openButton.addEventListener("click", () => {
@@ -66,13 +84,13 @@ closeButton.addEventListener("click", () => {
 });
 
 // Close button closes the dialog box with a return value
-closeWithReturnValueButton.addEventListener("click", () => {
+closeWithValueButton.addEventListener("click", () => {
   dialog.close("some value");
 });
 
 // Form close button closes the dialog box
 dialog.addEventListener("close", () => {
-  statusText.innerHTML = `Dialog closed. Return value: "${dialog.returnValue}"`;
+  log(`Dialog closed. Return value: "${dialog.returnValue}"`);
 });
 ```
 
diff --git a/files/en-us/web/api/htmldialogelement/close_event/index.md b/files/en-us/web/api/htmldialogelement/close_event/index.md
index 5c5aaa7097241f4..e47d0ae1ceefb98 100644
--- a/files/en-us/web/api/htmldialogelement/close_event/index.md
+++ b/files/en-us/web/api/htmldialogelement/close_event/index.md
@@ -35,21 +35,33 @@ A generic {{domxref("Event")}}.
 ```html
 
   
    
-    
+    
   
    
   
   
    Or hit the Esc key
    
     
 
-
+
+```
 
-
    
+```html hidden
+
    
 ```
 
 ```css hidden
-button,
-div {
-  margin: 0.5rem;
+#status-text {
+  height: 120px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const statusText = document.getElementById("status-text");
+function log(text) {
+  statusText.innerText = `${statusText.innerText}${text}\n`;
+  statusText.scrollTop = statusText.scrollHeight;
 }
 ```
 
@@ -59,20 +71,19 @@ div {
 const dialog = document.getElementById("dialog");
 const openButton = document.getElementById("open");
 const closeButton = document.getElementById("close");
-const statusText = document.getElementById("status-text");
-
-dialog.addEventListener("close", (event) => {
-  statusText.textContent = "dialog was closed";
-});
 
 openButton.addEventListener("click", () => {
   dialog.showModal();
-  statusText.textContent = "";
+  log("dialog: opened");
 });
 
 closeButton.addEventListener("click", () => {
   dialog.close();
 });
+
+dialog.addEventListener("close", (event) => {
+  log("dialog: closed");
+});
 ```
 
 #### Result
diff --git a/files/en-us/web/api/htmldialogelement/closedby/index.md b/files/en-us/web/api/htmldialogelement/closedby/index.md
index 9ba1ccc78e969fb..d541263f7ab33f9 100644
--- a/files/en-us/web/api/htmldialogelement/closedby/index.md
+++ b/files/en-us/web/api/htmldialogelement/closedby/index.md
@@ -37,7 +37,7 @@ If the `closedby` attribute is absent or invalid, it falls back to the **Auto**
 
   
    My dialog
    
   
    
-    Closable using the ESC key, or by clicking outside the dialog.
+    Closable using the Esc key, or by clicking outside the dialog.
     "Light dismiss" behavior.
   
    
     
diff --git a/files/en-us/web/api/htmldialogelement/index.md b/files/en-us/web/api/htmldialogelement/index.md
index b006529ca93316f..1458054d0d55ee5 100644
--- a/files/en-us/web/api/htmldialogelement/index.md
+++ b/files/en-us/web/api/htmldialogelement/index.md
@@ -19,7 +19,7 @@ The **`HTMLDialogElement`** interface provides methods to manipulate {{HTMLEleme
 _Also inherits properties from its parent interface, {{domxref("HTMLElement")}}._
 
 - {{domxref("HTMLDialogElement.closedBy")}}
-  - : A string that sets or returns the [`closedby`](/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby) attribute value of the `` element, which indicates the types of user actions that can be used to close the dialog.
+  - : A string that sets or returns the [`closedby`](/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby) HTML attribute, indicating the types of user actions that can be used to close the dialog.
 - {{domxref("HTMLDialogElement.open")}}
   - : A boolean value reflecting the [`open`](/en-US/docs/Web/HTML/Reference/Elements/dialog#open) HTML attribute, indicating whether the dialog is available for interaction.
 - {{domxref("HTMLDialogElement.returnValue")}}
@@ -30,13 +30,13 @@ _Also inherits properties from its parent interface, {{domxref("HTMLElement")}}.
 _Also inherits methods from its parent interface, {{domxref("HTMLElement")}}._
 
 - {{domxref("HTMLDialogElement.close()")}}
-  - : Closes the dialog. An optional string may be passed as an argument, updating the `returnValue` of the dialog.
+  - : Closes the dialog. An optional string may be passed as an argument, updating the {{domxref("HTMLDialogElement.returnValue", "returnValue")}} of the dialog.
 - {{domxref("HTMLDialogElement.requestClose()")}}
-  - : Requests to close the dialog. An optional string may be passed as an argument, updating the `returnValue` of the dialog.
+  - : Requests to close the dialog. An optional string may be passed as an argument, updating the {{domxref("HTMLDialogElement.returnValue", "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.
+  - : Displays the dialog as a modal, over the top of any other dialogs that might be present. Everything outside the dialog is {{DOMxRef("HTMLElement.inert", "inert")}} with interactions outside the dialog being blocked.
 
 ## Events
 
@@ -45,30 +45,35 @@ _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/cancel_event", "cancel")}}
-  - : Fired when the dialog is requested to close, whether with the escape key, or via the `HTMLDialogElement.requestClose()` method.
+  - : Fired when the dialog is requested to close, whether with the escape key, or via the {{domxref("HTMLDialogElement.close()", "requestClose()")}} method.
 - {{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/Reference/Elements/form#method).
+  - : Fired when the dialog is closed, whether with the escape key, the {{domxref("HTMLDialogElement.close()", "close()")}} method, or via submitting a form within the dialog with [`method="dialog"`](/en-US/docs/Web/HTML/Reference/Elements/form#method).
 
 ## Examples
 
-### Opening a modal dialog
+### Open / close a modal dialog
 
-The following example shows a button that, when clicked, uses the {{domxref("HTMLDialogElement.showModal()")}} function to open a modal {{htmlelement("dialog")}} containing a form.
+The following example shows a button that, when clicked, uses the {{domxref("HTMLDialogElement.showModal()", "showModal()")}} function to open a modal dialog containing a form.
 
 While open, everything other than the modal dialog's contents is inert.
-You can click the _Cancel_ button to close the dialog (via the {{domxref("HTMLDialogElement.close()")}} function), or submit the form via the _Confirm_ button.
+You can click the _Close_ button to close the dialog (via the {{domxref("HTMLDialogElement.close()", "close()")}} function), or submit the form via the _Confirm_ button.
 
-The example demonstrates how you might use all the "state change" events that can be fired on the dialog: {{domxref("HTMLDialogElement/cancel_event", "cancel")}} and {{domxref("HTMLDialogElement/close_event", "close")}}, and the inherited events {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}}, and {{domxref("HTMLElement/toggle_event", "toggle")}}.
+The example demonstrates:
+
+1. Closing a form with the {{domxref("HTMLDialogElement.close()", "close()")}} function
+2. Closing a form on form submit and setting the dialog {{domxref("HTMLDialogElement.returnValue", "returnValue")}}
+3. Closing a form with the Esc key
+4. "state change" events that can be fired on the dialog: {{domxref("HTMLDialogElement/cancel_event", "cancel")}} and {{domxref("HTMLDialogElement/close_event", "close")}}, and the inherited events {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}}, and {{domxref("HTMLElement/toggle_event", "toggle")}}.
 
 #### HTML
 
 ```html
-
-
-  
    
+
+  
+  
     
    
-      
-      
         
         
         
@@ -76,24 +81,21 @@ The example demonstrates how you might use all the "state change" events that ca
       
     
    
     
    
-      
       
     
    
   
 
    
 
-
    
-  
-
    
+
 ```
 
 ```html hidden
-
    
+
    
 ```
 
 ```css hidden
-#log {
-  height: 150px;
+#status-text {
+  height: 120px;
   overflow: scroll;
   padding: 0.5rem;
   border: 1px solid black;
@@ -101,55 +103,68 @@ The example demonstrates how you might use all the "state change" events that ca
 ```
 
 ```js hidden
-const logElement = document.querySelector("#log");
+const statusText = document.getElementById("status-text");
 function log(text) {
-  logElement.innerText = `${logElement.innerText}${text}\n`;
-  logElement.scrollTop = logElement.scrollHeight;
+  statusText.innerText = `${statusText.innerText}${text}\n`;
+  statusText.scrollTop = statusText.scrollHeight;
 }
 ```
 
 #### JavaScript
 
-##### Showing the dialog
+##### Open the dialog
 
-The code first gets objects for the {{htmlelement("button")}} elements, the {{htmlelement("dialog")}} element, and the {{htmlelement("select")}} element.
-It then adds a listener to call the {{domxref("HTMLDialogElement.showModal()")}} function when the _Update_ button is clicked.
+The code first gets objects for the {{htmlelement("dialog")}} element, the {{htmlelement("button")}} elements, and the {{htmlelement("select")}} element.
+It then adds a listener to call the {{domxref("HTMLDialogElement.showModal()")}} function when the _Open Dialog_ button is clicked.
 
 ```js
-const updateButton = document.getElementById("updateDetails");
-const confirmButton = document.getElementById("submit");
-const cancelButton = document.getElementById("cancel");
-const dialog = document.getElementById("favDialog");
-const selectElement = document.getElementById("favAnimal");
-
-// Update button opens a modal dialog
-updateButton.addEventListener("click", () => {
+const dialog = document.getElementById("dialog");
+const openButton = document.getElementById("open");
+
+// Open button opens a modal dialog
+openButton.addEventListener("click", () => {
+  log(`dialog: showModal()`);
   dialog.showModal();
 });
 ```
 
-##### Cancel and confirm buttons
+##### Close the dialog when the _Close_ button is clicked
 
-Next we add listeners to the _Confirm_ and _Cancel_ button `click` events.
-The handlers call {{domxref("HTMLDialogElement.close()")}} with the selection value (if present) and no value, which in turn set the return value of the dialog ({{domxref("HTMLDialogElement.returnValue")}}) to the selection value and `null`, respectively.
+Next we add a listener to the _Close_ button {{domxref("Element/click_event", "click")}} event. The handler set the {{domxref("HTMLDialogElement.returnValue", "returnValue")}} and calls the {{domxref("HTMLDialogElement.close()", "close()")}} function to close the dialog.
 
 ```js
-// Confirm button closes dialog if there is a selection.
-confirmButton.addEventListener("click", () => {
-  if (selectElement.value) {
-    // Set dialog.returnValue to selected value
-    dialog.close(selectElement.value);
-  }
+// Close button closes the dialog box
+const closeButton = document.getElementById("close");
+closeButton.addEventListener("click", () => {
+  dialog.returnValue = ""; // Reset return value
+  log(`dialog: close()`);
+  dialog.close();
+  // Alternatively, we could use dialog.requestClose(""); with an empty return value.
 });
+```
+
+##### Close the dialog when _Confirm_ button is clicked via form submission
 
-// Cancel button closes the dialog box
-cancelButton.addEventListener("click", () => {
-  dialog.close(); // Set dialog.returnValue to null
+Next we add a listener to the {{htmlelement("form")}} {{domxref("HTMLFormElement.submit_event", "submit")}} event.
+The form is submitted when the required {{htmlelement("select")}} element has a value _Confirm_ button is clicked. If the {{htmlelement("select")}} element does not have a value the form will not submit and the dialog will remain open.
+
+```js
+// Confirm button closes dialog if there is a selection.
+const form = document.getElementById("form");
+const selectElement = document.getElementById("fav-animal");
+form.addEventListener("submit", () => {
+  log(`form: submit`);
+  // Set the return value to the selected option value
+  dialog.returnValue = selectElement.value;
+  // We don't need to close the dialog here
+  // submitting the form with method="dialog" will do that automatically.
+  // dialog.close();
 });
 ```
 
-Calling `close()` also fires the {{domxref("HTMLDialogElement/close_event", "close")}} event, which we implement below by logging the return value of the dialog.
-If the _Confirm_ button was clicked this should be the selected value in the dialog, otherwise it should be `null`.
+##### Get the `returnValue` on `close`
+
+Calling {{domxref("HTMLDialogElement.close()", "close()")}} (or successfully submitting a form with `method="dialog`") fires the {{domxref("HTMLDialogElement/close_event", "close")}} event, which we implement below by logging the return value of the dialog.
 
 ```js
 dialog.addEventListener("close", (event) => {
@@ -157,12 +172,12 @@ dialog.addEventListener("close", (event) => {
 });
 ```
 
-##### Cancel event
+##### `cancel` event
 
 The {{domxref("HTMLDialogElement/cancel_event", "cancel")}} event is fired when "platform specific methods" are used to close the dialog, such as the Esc key.
-It is also fired when the `HTMLDialogElement.requestClose()` method is called.
+It is also fired when the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method is called.
 The event is "cancelable" which means that we could use it to prevent the dialog from closing.
-Here we just treat the cancel as a "close" operation, and reset the {{domxref("HTMLDialogElement.returnValue")}} to `""` to clear any value that may have been set.
+Here we just treat the cancel as a "close" operation, and reset the {{domxref("HTMLDialogElement.returnValue", "returnValue")}} to `""` to clear any value that may have been set.
 
 ```js
 dialog.addEventListener("cancel", (event) => {
@@ -171,25 +186,25 @@ dialog.addEventListener("cancel", (event) => {
 });
 ```
 
-##### Toggle event
+##### `toggle` event
 
-The [`toggle` event](/en-US/docs/Web/API/HTMLElement/toggle_event) (inherited from `HTMLElement`) is fired just after a dialog has opened or closed (but before the `closed` event).
+The {{domxref("HTMLElement/toggle_event", "toggle")}} event (inherited from {{domxref("HTMLElement", "HTMLElement")}}) is fired just after a dialog has opened or closed (but before the {{domxref("HTMLDialogElement/close_event", "close")}} event).
 
-Here we add a listener to log when the Dialog opens and closes.
+Here we add a listener to log when the dialog opens and closes.
 
 > [!NOTE]
-> The `toggle` and `beforetoggle` events may not be fired at dialog elements on all browsers.
-> On these browser versions you can instead check the {{domxref("HTMLDialogElement.open")}} property after attempting to open/close the dialog.
+> The {{domxref("HTMLElement/toggle_event", "toggle")}} and {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} events may not be fired at dialog elements on all browsers.
+> On these browser versions you can instead check the {{domxref("HTMLDialogElement.open", "open")}} property after attempting to open/close the dialog.
 
 ```js
 dialog.addEventListener("toggle", (event) => {
-  log(`toggle_event: Dialog ${event.newState}`);
+  log(`toggle event: newState: ${event.newState}`);
 });
 ```
 
-##### Beforetoggle event
+##### `beforetoggle` event
 
-The [`beforetoggle` event](/en-US/docs/Web/API/HTMLElement/beforetoggle_event) (inherited from `HTMLElement`) is a cancellable event that is fired just before a dialog is opened or closed.
+The {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event (inherited from {{domxref("HTMLElement", "HTMLElement")}}) is a cancellable event that is fired just before a dialog is opened or closed.
 If needed, this can be used to prevent a dialog from showing, or to perform actions on other elements that are affected by the dialog open/close state, such as adding classes on them to trigger animations.
 
 In this case we just log the old and new state.
@@ -212,9 +227,9 @@ dialog.addEventListener("beforetoggle", (event) => {
 #### Result
 
 Try out the example below.
-Note that both `Confirm` and `Cancel` buttons result in the `close` event being fired, and that the result should reflect the selected dialog option.
+Note that both `Confirm` and `Close` buttons result in the {{domxref("HTMLDialogElement/close_event", "close")}} event being fired, and that the result should reflect the selected dialog option.
 
-{{EmbedLiveSample("Opening a modal dialog", '100%', "250px")}}
+{{EmbedLiveSample("Open / close a modal dialog", '100%', "250px")}}
 
 ## Specifications
 
diff --git a/files/en-us/web/api/htmldialogelement/open/index.md b/files/en-us/web/api/htmldialogelement/open/index.md
index 89d648128b560e2..43caa51b19a6ff0 100644
--- a/files/en-us/web/api/htmldialogelement/open/index.md
+++ b/files/en-us/web/api/htmldialogelement/open/index.md
@@ -36,20 +36,36 @@ button.
   
     
 
-
    
-  
-
    
+
+```
 
-
    Dialog closed
    
+```html hidden
+
    
+```
+
+```css hidden
+#status-text {
+  height: 120px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const statusText = document.getElementById("status-text");
+function log(text) {
+  statusText.innerText = `${statusText.innerText}${text}\n`;
+  statusText.scrollTop = statusText.scrollHeight;
+}
 ```
 
 ```js
 const dialog = document.getElementById("dialog");
 const openButton = document.getElementById("open");
-const statusText = document.getElementById("status-text");
 
 function openCheck(dialog) {
-  statusText.innerText = dialog.open ? "Dialog open" : "Dialog closed";
+  log(dialog.open ? "Dialog: open" : "Dialog: closed");
 }
 
 openButton.addEventListener("click", () => {
@@ -64,7 +80,7 @@ dialog.addEventListener("close", () => {
 
 ### Result
 
-{{ EmbedLiveSample('Examples', '100%', '200px') }}
+{{ EmbedLiveSample('Examples', '100%', '250px') }}
 
 ## Specifications
 
diff --git a/files/en-us/web/api/htmldialogelement/requestclose/index.md b/files/en-us/web/api/htmldialogelement/requestclose/index.md
index 013666dee52f40e..a292633f8d00a18 100644
--- a/files/en-us/web/api/htmldialogelement/requestclose/index.md
+++ b/files/en-us/web/api/htmldialogelement/requestclose/index.md
@@ -55,8 +55,27 @@ Preventing the dialog from closing is demonstrated with a checkbox.
     
 
 
+```
+
+```html hidden
+
    
+```
 
-
    
+```css hidden
+#status-text {
+  height: 120px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const statusText = document.getElementById("status-text");
+function log(text) {
+  statusText.innerText = `${statusText.innerText}${text}\n`;
+  statusText.scrollTop = statusText.scrollHeight;
+}
 ```
 
 ```js
@@ -65,7 +84,6 @@ const openButton = document.getElementById("open");
 const closeButton = document.getElementById("close");
 const closeWithValueButton = document.getElementById("close-w-value");
 const preventCloseInput = document.getElementById("prevent-close");
-const statusText = document.getElementById("status-text");
 
 // Update button opens a modal dialog
 openButton.addEventListener("click", () => {
@@ -88,15 +106,15 @@ closeWithValueButton.addEventListener("click", () => {
 // Fired when requestClose() is called
 // Prevent the dialog from closing by calling event.preventDefault()
 dialog.addEventListener("cancel", (event) => {
-  if (cancelCloseInput.checked) {
-    statusText.innerText = "Dialog close cancelled";
+  if (preventCloseInput.checked) {
+    log("Dialog close cancelled");
     event.preventDefault();
   }
 });
 
 // cancel event is not prevented, dialog will close
 dialog.addEventListener("close", () => {
-  statusText.innerHTML = `Dialog closed. Return value: "${dialog.returnValue}"`;
+  log(`Dialog closed. Return value: "${dialog.returnValue}"`);
 });
 ```
 
diff --git a/files/en-us/web/api/htmldialogelement/returnvalue/index.md b/files/en-us/web/api/htmldialogelement/returnvalue/index.md
index d5cae56233f3685..3a8b99989654cc2 100644
--- a/files/en-us/web/api/htmldialogelement/returnvalue/index.md
+++ b/files/en-us/web/api/htmldialogelement/returnvalue/index.md
@@ -36,8 +36,28 @@ If the user dismisses the dialog without clicking a button (for example, by pres
   
   
     
-
-
    
+
+```
+
+```html hidden
+
    
+```
+
+```css hidden
+#status-text {
+  height: 120px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+```js hidden
+const statusText = document.getElementById("status-text");
+function log(text) {
+  statusText.innerText = `${statusText.innerText}${text}\n`;
+  statusText.scrollTop = statusText.scrollHeight;
+}
 ```
 
 #### JavaScript
@@ -47,7 +67,6 @@ const dialog = document.getElementById("dialog");
 const openButton = document.getElementById("open");
 const declineButton = document.getElementById("decline");
 const acceptButton = document.getElementById("accept");
-const statusText = document.getElementById("status-text");
 
 openButton.addEventListener("click", () => {
   // Reset the return value on each open
@@ -63,7 +82,7 @@ function closeDialog(event) {
 }
 
 function updateReturnValue() {
-  statusText.innerHTML = `Return value: "${dialog.returnValue}"`;
+  log(`Return value: "${dialog.returnValue}"`);
 }
 
 declineButton.addEventListener("click", closeDialog);
@@ -76,7 +95,7 @@ dialog.addEventListener("close", updateReturnValue);
 
 Try clicking "Review ToS", then choosing the "Accept" or "Decline" buttons in the dialog, or dismissing the dialog by pressing the Esc key, and observe the different status updates.
 
-{{ EmbedLiveSample('Checking the return value', '100%', '200px') }}
+{{ EmbedLiveSample('Checking the return value', '100%', "250px")}}
 
 ## Specifications
 
diff --git a/files/en-us/web/api/htmldialogelement/showmodal/index.md b/files/en-us/web/api/htmldialogelement/showmodal/index.md
index f7bfbc36ad7e2f6..f964b8dbf63d1bf 100644
--- a/files/en-us/web/api/htmldialogelement/showmodal/index.md
+++ b/files/en-us/web/api/htmldialogelement/showmodal/index.md
@@ -69,7 +69,7 @@ closeButton.addEventListener("click", () => {
 
 #### Result
 
-{{EmbedLiveSample("Opening a modal dialog")}}
+{{EmbedLiveSample("Basic usage")}}
 
 ## Specifications
 
diff --git a/files/en-us/web/api/htmlelement/beforetoggle_event/index.md b/files/en-us/web/api/htmlelement/beforetoggle_event/index.md
index c9544238cdaf3ed..884215df4805e3e 100644
--- a/files/en-us/web/api/htmlelement/beforetoggle_event/index.md
+++ b/files/en-us/web/api/htmlelement/beforetoggle_event/index.md
@@ -193,7 +193,7 @@ popover.hidePopover();
 
 ### Other examples
 
-- [Opening a modal dialog](/en-US/docs/Web/API/HTMLDialogElement#opening_a_modal_dialog) example in `HTMLDialogElement`
+- [Opening a modal dialog](/en-US/docs/Web/API/HTMLDialogElement#open_close_a_modal_dialog) example in `HTMLDialogElement`
 
 ## Specifications
 
diff --git a/files/en-us/web/api/htmlelement/toggle_event/index.md b/files/en-us/web/api/htmlelement/toggle_event/index.md
index 9dac8536e2f13a6..ed5a4d50f4e16e1 100644
--- a/files/en-us/web/api/htmlelement/toggle_event/index.md
+++ b/files/en-us/web/api/htmlelement/toggle_event/index.md
@@ -108,7 +108,7 @@ popover.hidePopover();
 
 ### Other examples
 
-- [Opening a modal dialog](/en-US/docs/Web/API/HTMLDialogElement#opening_a_modal_dialog) example in `HTMLDialogElement`
+- [Opening a modal dialog](/en-US/docs/Web/API/HTMLDialogElement#open_close_a_modal_dialog) example in `HTMLDialogElement`
 
 ## Specifications
 

From f492cc0afd0700d877bc490817435a51bc61c374 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Tue, 2 Dec 2025 10:05:35 +1100
Subject: [PATCH 5/7] Update
 files/en-us/web/api/htmldialogelement/cancel_event/index.md

---
 files/en-us/web/api/htmldialogelement/cancel_event/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/htmldialogelement/cancel_event/index.md b/files/en-us/web/api/htmldialogelement/cancel_event/index.md
index 37622f7fa4c0824..019cff99fdb39cd 100644
--- a/files/en-us/web/api/htmldialogelement/cancel_event/index.md
+++ b/files/en-us/web/api/htmldialogelement/cancel_event/index.md
@@ -38,7 +38,7 @@ A generic {{domxref("Event")}}.
 
 The following example shows a button that, when clicked, opens a {{htmlelement("dialog")}} via the {{domxref("HTMLDialogElement.showModal()", "showModal()")}} method.
 
-From there you can will trigger the `cancel` event by either clicking _Request Close_ button to close the dialog (via the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method) or press the Esc key.
+From there you can trigger the `cancel` event by either clicking _Request Close_ button to close the dialog (via the {{domxref("HTMLDialogElement.requestClose()", "requestClose()")}} method), or press the Esc key.
 
 Preventing the dialog from closing is demonstrated with a checkbox.
 

From 2c5c89413adc48074bdb16d8efd274cf58cf23c3 Mon Sep 17 00:00:00 2001
From: Leevi Graham 
Date: Tue, 2 Dec 2025 19:47:56 +1100
Subject: [PATCH 6/7] Apply suggestion from @hamishwillee

Co-authored-by: Hamish Willee 
---
 files/en-us/web/api/htmldialogelement/closedby/index.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/files/en-us/web/api/htmldialogelement/closedby/index.md b/files/en-us/web/api/htmldialogelement/closedby/index.md
index d541263f7ab33f9..8621223aa3980d7 100644
--- a/files/en-us/web/api/htmldialogelement/closedby/index.md
+++ b/files/en-us/web/api/htmldialogelement/closedby/index.md
@@ -37,8 +37,7 @@ If the `closedby` attribute is absent or invalid, it falls back to the **Auto**
 
   
    My dialog
    
   
    
-    Closable using the Esc key, or by clicking outside the dialog.
-    "Light dismiss" behavior.
+    Closable using the Esc key, or by clicking outside the dialog ("light dismiss").
   
    
     
 ```

From 8d5410672d5a802d5c4fe89cfeea657b6ab856ab Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Fri, 5 Dec 2025 09:35:35 +1100
Subject: [PATCH 7/7] Update
 files/en-us/web/api/htmldialogelement/closedby/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 files/en-us/web/api/htmldialogelement/closedby/index.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/files/en-us/web/api/htmldialogelement/closedby/index.md b/files/en-us/web/api/htmldialogelement/closedby/index.md
index 8621223aa3980d7..0c4074dd2ee0e16 100644
--- a/files/en-us/web/api/htmldialogelement/closedby/index.md
+++ b/files/en-us/web/api/htmldialogelement/closedby/index.md
@@ -37,7 +37,8 @@ If the `closedby` attribute is absent or invalid, it falls back to the **Auto**
 
   
    My dialog
    
   
    
-    Closable using the Esc key, or by clicking outside the dialog ("light dismiss").
+    Closable using the Esc key, or by clicking outside the dialog
+    ("light dismiss").
   
    
     
 ```