docs: clarify <dialog> Esc close request behavior

[ross-u]

Description

Corrects the explanation of how a modal <dialog> is dismissed when the user presses the Esc key. It clarifies the sequence of events, cancel followed by close, if not prevented, and explains that no explicit return value is provided in this case leaving dialog.returnValue as an empty string.

Motivation

I would like to help and contribute to the MDN documentation and thought to give it a shot with this small issue first. 🙂

Additional details

Related issues and pull requests

Fixes #41656

[github-actions]

Preview URLs (1 page)

• /en-US/docs/Web/HTML/Reference/Elements/dialog

(comment last updated: 2026-02-02 14:19:26)

[chrisdavidmills]

Hi @ross-u, and thank you for your work in fixing this issue.

I've provided a suggestion to tighten up the text a bit, however, I think there is a bigger concern here — the behavior works as described, but only in Chrome.

If you try it in Firefox and Safari, the returnValue is set to an empty string when you press Esc, only if you haven't already selected a value from the dialog dropdown or pressed the dialog "Cancel" button. If you've done one of those two things, then on subsequent presses of the "Show the dialog" button, when you press the Esc key, the returnValue remains set to the previously selected dialog value.

I don't know if this is old behavior, and Chrome's behavior has been updated to spec behavior, or something else. But it is worth investigating this and thinking about how to communicate it in the doc.

[Josh-Cena]

Asked Codex to investigate this.

Firefox’s behavior is correct for the returnValue difference reported in the PR. Escape should preserve the previous value; Chrome’s reset to "" is a bug.

The specification separates two things:

• Events: Escape initiates a close request. The dialog fires cancel; if the request isn’t canceled, it closes and queues a close event. The [dialog event test](https://github.com/web-platform-tests/wpt/blob/master/html/semantics/interactive-elements/the-dialog-element/dialog-cancel-events.html) explicitly checks that order.
• Return value: returnValue starts as "" when the element is created, not each time it opens. The close watcher supplies an internal “request close return value,” initially null. The closing algorithm updates returnValue only when its result is non-null. Thus, ordinary Escape dismissal preserves the existing value. See the [returnValue definition](https://html.spec.whatwg.org/multipage/interactive-elements.html#dom-dialog-returnvalue) and [closing algorithm, step 9](https://html.spec.whatwg.org/multipage/interactive-elements.html#close-the-dialog).

For example, after dialog.close("cancel"), reopening the same dialog and pressing Escape should leave dialog.returnValue === "cancel".

Chromium’s implementation explains the discrepancy. Its constructor initializes request_close_return_value_ to "". CloseWatcherFiredClose() passes that to close(), which overwrites return_value_ because the string isn’t null. That directly explains the reported reset. See [Chromium’s dialog implementation](https://github.com/chromium/chromium/blob/main/third_party/blink/renderer/core/html/html_dialog_element.cc). This is source inspection, not a fresh browser reproduction.

The [PR](#42975) therefore fixes the incorrect assertion that close doesn’t fire, but introduces an incorrect assertion about an empty return value. I’d suggest:

Pressing Esc requests that the dialog close, firing a cancel event. If the request is not canceled, the dialog closes and fires a close event. The returnValue remains unchanged, retaining its previous value or its initial empty string.

Any note about Chrome resetting the value should describe it as a browser discrepancy, rather than the specified behavior.