From 16c8ed1f9d22fc9d9d6b62b6a3444171fd4fdde9 Mon Sep 17 00:00:00 2001
From: internet-account2 <190649829+internet-account2@users.noreply.github.com>
Date: Thu, 2 Jul 2026 18:43:53 +0200
Subject: [PATCH 1/2] Fix "Handling the return value" example

- Code description was inaccurate
- Falsely stated that "Esc" doesn't trigger close event
- "Confirm" button having a value that is never used is confusing
- Code didn't check for the initial "" returnValue, which seems like an oversight to me
---
 .../web/html/reference/elements/dialog/index.md | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/files/en-us/web/html/reference/elements/dialog/index.md b/files/en-us/web/html/reference/elements/dialog/index.md
index 7f5af8bbb7f82e9..6c78e3fb3067347 100644
--- a/files/en-us/web/html/reference/elements/dialog/index.md
+++ b/files/en-us/web/html/reference/elements/dialog/index.md
@@ -273,9 +273,9 @@ When the modal dialog is displayed, it appears above any other dialogs that migh
 
 This example demonstrates the [`returnValue`](/en-US/docs/Web/API/HTMLDialogElement/returnValue) of the `<dialog>` element and how to close a modal dialog by using a form. By default, the `returnValue` is the empty string or the value of the button that submits the form within the `<dialog>` element, if there is one.
 
-This example opens a modal dialog when the "Show the dialog" button is activated. The dialog contains a form with a {{HTMLElement("select")}} and two {{HTMLElement("button")}} elements, which default to `type="submit"`. An event listener 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 `returnValue` is `cancel`.
+This example opens a modal dialog when the "Show the dialog" button is activated. The dialog contains a form with a {{HTMLElement("select")}} and two {{HTMLElement("button")}} elements, which default to `type="submit"`. If the "Confirm" button is activated to close the dialog, an event listener sets `returnValue` to the current value of the select box instead of the button's value. If the dialog is closed by pressing the "Cancel" button, the `returnValue` is `cancel`.
 
-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 `returnValue` is not updated, and the `close` event doesn't occur, so the text in the {{HTMLElement("output")}} is not updated.
+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 `returnValue` is not updated, but the `close` event still occurs, so the text in the {{HTMLElement("output")}} is "updated" with the (unchanged) `returnValue`.
 
 #### HTML
 
@@ -287,7 +287,7 @@ When the dialog is closed, the return value is displayed under the "Show the dia
       <label>
         Favorite animal:
         <select>
-          <option value="default">Choose…</option>
+          <option value="">Choose…</option>
           <option>Brine shrimp</option>
           <option>Red panda</option>
           <option>Spider monkey</option>
@@ -296,7 +296,7 @@ When the dialog is closed, the return value is displayed under the "Show the dia
     </p>
     <div>
       <button value="cancel" formmethod="dialog">Cancel</button>
-      <button id="confirmBtn" value="default">Confirm</button>
+      <button id="confirmBtn">Confirm</button>
     </div>
   </form>
 </dialog>
@@ -327,12 +327,13 @@ showButton.addEventListener("click", () => {
   favDialog.showModal();
 });
 
-// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"], triggering a close event.
+// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"],
+// "Esc" was pressed, or `favDialog.close()` was called, triggering a close event.
 favDialog.addEventListener("close", (e) => {
   outputBox.value =
-    favDialog.returnValue === "default"
-      ? "No return value."
-      : `ReturnValue: ${favDialog.returnValue}.`; // Have to check for "default" rather than empty string
+    favDialog.returnValue === ""
+      ? "No return value." // returnValue had its default "" starting value, or the select box's "Choose…" option's "" value
+      : `ReturnValue: ${favDialog.returnValue}.`;
 });
 
 // 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.

From 0992149960f0569fce36d8217bb8846b1226bcb1 Mon Sep 17 00:00:00 2001
From: internet-account2 <190649829+internet-account2@users.noreply.github.com>
Date: Fri, 3 Jul 2026 15:46:42 +0200
Subject: [PATCH 2/2] "Handling the return value": mention cancel event

should make it clear that it's possible to separately handle the cancel event?
---
 files/en-us/web/html/reference/elements/dialog/index.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/files/en-us/web/html/reference/elements/dialog/index.md b/files/en-us/web/html/reference/elements/dialog/index.md
index 6c78e3fb3067347..feeae55cf29ad25 100644
--- a/files/en-us/web/html/reference/elements/dialog/index.md
+++ b/files/en-us/web/html/reference/elements/dialog/index.md
@@ -275,7 +275,7 @@ This example demonstrates the [`returnValue`](/en-US/docs/Web/API/HTMLDialogElem
 
 This example opens a modal dialog when the "Show the dialog" button is activated. The dialog contains a form with a {{HTMLElement("select")}} and two {{HTMLElement("button")}} elements, which default to `type="submit"`. If the "Confirm" button is activated to close the dialog, an event listener sets `returnValue` to the current value of the select box instead of the button's value. If the dialog is closed by pressing the "Cancel" button, the `returnValue` is `cancel`.
 
-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 `returnValue` is not updated, but the `close` event still occurs, so the text in the {{HTMLElement("output")}} is "updated" with the (unchanged) `returnValue`.
+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 `returnValue` is not updated, a `cancel` event gets triggered, and finally a `close` event occurs, so the text in the {{HTMLElement("output")}} is "updated" with the (unchanged) `returnValue`.
 
 #### HTML
 
@@ -327,8 +327,9 @@ showButton.addEventListener("click", () => {
   favDialog.showModal();
 });
 
-// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"],
-// "Esc" was pressed, or `favDialog.close()` was called, triggering a close event.
+// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"]
+// or `favDialog.close()` was called, triggering a close event.
+// Or "Esc" was pressed, followed by a cancel event, which is also followed by a close event.
 favDialog.addEventListener("close", (e) => {
   outputBox.value =
     favDialog.returnValue === ""