Modernize beforeunload event information #29595

chrisdavidmills · 2023-10-11T13:13:06Z

Description

Chrome 119 includes an update to the beforeunload event — it now triggers the "leave page?" confirmation dialog when e.preventDefault() is called upon the event firing, and doesn't do that when e.returnValue is set to an empty string. This is great because Chrome now behaves like other browsers, so this event is immediately more useful than it was.

This PR:

Brings the corresponding MDN content up-to-date, telling a clearer story about the state of the platform now.
Adds better, clearer examples.
Modernizes page structures, makes them more consistent with the rest of the site.
Reduces repetition and generally makes the content easier to follow.

Also related:

See Update Chrome beforeunload dialog control behavior browser-compat-data#20942 for the corresponding compat data update.
See https://chromestatus.com/feature/4968823574233088 for the implementation details; the engineer has informed me that the actual release version will be 119).

Motivation

Additional details

Related issues and pull requests

github-actions · 2023-10-11T13:16:41Z

Preview URLs

External URLs (3)

URL: /en-US/docs/Web/API/Window/beforeunload_event
Title: Window: beforeunload event

https://developer.chrome.com/blog/page-lifecycle-api/ (1 time) (Note! This may be a new URL 👀)
https://web.dev/bfcache/ (1 time) (Note! This may be a new URL 👀)
https://www.igvita.com/2015/11/20/dont-lose-user-and-app-state-use-page-visibility/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-10-12 08:18:11)

wbamberg · 2023-10-11T18:37:48Z

files/en-us/web/api/window/beforeunload_event/index.md

- {{domxref("SVGSVGElement")}}
-
-## Security
+- Only show the dialog box if the frame or any embedded frame receives a user gesture or user interaction.


I'm not that clear what this means and how it differs from sticky activation (the third condition). I understand the sticky activation requirement (and think it is maybe worth spelling out: the point being that if the user has never interacted with the page, then there is no user data to save, so no legitimate use case for the dialog).

Oops, I was supposed to merge those into one point as they are basically the same thing. I've done that in my next commit, as well as adding your thought about "if the user has never interacted..."; I think that is useful. Thanks!

wbamberg · 2023-10-11T18:45:04Z

files/en-us/web/api/beforeunloadevent/index.md

+  event.returnValue = "any non-empty string value";
+  // Equivalent to invoking event.preventDefault();


I don't think this example should be showing the non-recommended version (setting returnValue).

Yeah, you're right. I've updated it to show the same example as on the event page, and I've added a note at the bottom of the section to say that the returnValue property can also be used, but it is legacy and not best practice.

wbamberg · 2023-10-11T18:46:11Z

files/en-us/web/api/beforeunloadevent/index.md

+  if (event.target.value !== "") {
+    window.addEventListener("beforeunload", beforeUnloadHandler);
+  } else {
+    window.removeEventListener("beforeunload", beforeUnloadHandler);
+  }


Why add/remove listeners on input, rather than always have the beforeunload listener, but conditionally call preventDefault() based on the value of target? It seems like that would be more efficient.

For reasons explained in the "Usage notes" section of the event page, most critically the one about Firefox not placing pages in the bfcache if they have beforeunload listeners.

Yes, I just realised this. Maybe worth mentioning in the description of this example to save other people from making my mistake!

Good call; done.

wbamberg · 2023-10-11T18:49:40Z

files/en-us/web/api/beforeunloadevent/index.md


-The `beforeunload` event is fired when the window, the document and its resources are about to be unloaded.
+The `returnValue` property defined on `BeforeUnloadEvent`, when set to a non-empty string value, triggers a browser-generated confirmation dialog. This dialog asks users to confirm if they _really_ want to leave the page when they try to close or reload it, or navigate somewhere else. It is intended to help prevent loss of unsaved data.


I sort of see the point of describing this property here, but I think it would be better just to describe it in the returnValue page, and adapt the note slightly like:

> **Note:** The `returnValue` property of this interface is...

Otherwise it looks a bit odd that you are going to special lengths to describe this property in this paragraph, then undercutting it immediately in the note.

Agreed. I've removed most of this text, making sure it is covered in the returnValue page itself, and added a note about it being legacy to the returnValue description on the BeforeUnloadEvent page. This seemed like a better place for it to go.

wbamberg · 2023-10-11T18:50:31Z

files/en-us/web/api/beforeunloadevent/returnvalue/index.md

+
+## Value
+
+`returnValue` is initiailized to an empty string (`""`) value.


Suggested change

`returnValue` is initiailized to an empty string (`""`) value.

`returnValue` is initialized to an empty string (`""`) value.

Fixed in next commit; thanks!

wbamberg · 2023-10-11T18:51:30Z

files/en-us/web/api/beforeunloadevent/returnvalue/index.md

+
+`returnValue` is initiailized to an empty string (`""`) value.
+
+Setting it to just about any [truthy](/en-US/docs/Glossary/Truthy) value will cause the dialog to be triggered on page close/reload.


Might be worth repeating or linking to the extra conditions (e.g. sticky activation) or this will mislead people.

Agreed. I've added this info to the returnValue page.

dizhang168

This is looking really good, thanks for updating the docs! My concern is that there is no mention of the return "non-empty string" pattern, which is likely still used by a lot of web developers.

dizhang168 · 2023-10-11T18:55:12Z

files/en-us/web/api/window/beforeunload_event/index.md

-The HTML specification states that calls to {{domxref("window.alert()")}}, {{domxref("window.confirm()")}}, and {{domxref("window.prompt()")}} methods may be ignored during this event. See the [HTML specification](https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#user-prompts) for more details.
+- Calling the event object's {{domxref("Event.preventDefault()", "preventDefault()")}} method.
+- Setting the event object's {{domxref("BeforeUnloadEvent.returnValue", "returnValue")}} property to a non-empty string value.
+


Note that returning a value (e.g. "return "Not empty string") will also trigger the cancel dialog. However, that behavior is weird as it doesn't work on addEventListener, but does work on onbeforeunload. It is a legacy behavior and should still be mentioned on the docs.

You can read more context at crbug.com/809277.

Ah, good call, thank you! I have mentioned this now, both in the list of methods for triggering the dialog, and in a comment in the code example.

…ent into beforeunload-update

wbamberg

👍 thank you Chris! Approving but leaving open in case @dizhang168 wants to verify that their comments are addressed. But this is good as far as I am concerned.

dizhang168

LGTM! (can't approve as I am not a repo owner)

Modernize beforeunload event information

2f7b3ed

chrisdavidmills requested a review from a team as a code owner October 11, 2023 13:13

chrisdavidmills requested review from wbamberg and removed request for a team October 11, 2023 13:13

github-actions bot added the Content:WebAPI Web API docs label Oct 11, 2023

wbamberg reviewed Oct 11, 2023

View reviewed changes

dizhang168 reviewed Oct 11, 2023

View reviewed changes

chrisdavidmills added 2 commits October 12, 2023 08:29

Make fixes for wbamberg and dizhang168 comments

c426e35

Merge branch 'main' into beforeunload-update

263ca46

chrisdavidmills requested review from wbamberg and dizhang168 October 12, 2023 07:37

chrisdavidmills added 3 commits October 12, 2023 09:06

Make sure reasons for the code example structure are clearly stated

ffae2e4

Merge branch 'beforeunload-update' of github.com:chrisdavidmills/cont…

7de73e3

…ent into beforeunload-update

other small fixes

1231c54

wbamberg approved these changes Oct 12, 2023

View reviewed changes

dizhang168 reviewed Oct 12, 2023

View reviewed changes

wbamberg merged commit 26f6807 into mdn:main Oct 12, 2023

chrisdavidmills deleted the beforeunload-update branch October 13, 2023 07:04

wbamberg mentioned this pull request Oct 16, 2023

beforeunload demo not work at all #29655

Closed

chrisdavidmills mentioned this pull request Oct 18, 2023

Add legacy support to beforeunload examples #29703

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modernize beforeunload event information #29595

Modernize beforeunload event information #29595

chrisdavidmills commented Oct 11, 2023

github-actions bot commented Oct 11, 2023 •

edited

Loading

wbamberg Oct 11, 2023

chrisdavidmills Oct 12, 2023

wbamberg Oct 11, 2023

chrisdavidmills Oct 12, 2023

wbamberg Oct 11, 2023

chrisdavidmills Oct 12, 2023

wbamberg Oct 12, 2023

chrisdavidmills Oct 12, 2023

wbamberg Oct 11, 2023

chrisdavidmills Oct 12, 2023

wbamberg Oct 11, 2023

chrisdavidmills Oct 12, 2023

wbamberg Oct 11, 2023

chrisdavidmills Oct 12, 2023

dizhang168 left a comment

dizhang168 Oct 11, 2023

chrisdavidmills Oct 12, 2023

wbamberg left a comment

dizhang168 left a comment

		event.returnValue = "any non-empty string value";
		// Equivalent to invoking event.preventDefault();


		The `beforeunload` event is fired when the window, the document and its resources are about to be unloaded.
		The `returnValue` property defined on `BeforeUnloadEvent`, when set to a non-empty string value, triggers a browser-generated confirmation dialog. This dialog asks users to confirm if they _really_ want to leave the page when they try to close or reload it, or navigate somewhere else. It is intended to help prevent loss of unsaved data.


		## Value

		`returnValue` is initiailized to an empty string (`""`) value.

	`returnValue` is initiailized to an empty string (`""`) value.
	`returnValue` is initialized to an empty string (`""`) value.


		`returnValue` is initiailized to an empty string (`""`) value.

		Setting it to just about any [truthy](/en-US/docs/Glossary/Truthy) value will cause the dialog to be triggered on page close/reload.

Modernize beforeunload event information #29595

Modernize beforeunload event information #29595

Conversation

chrisdavidmills commented Oct 11, 2023

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Oct 11, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dizhang168 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

dizhang168 left a comment

Choose a reason for hiding this comment

github-actions bot commented Oct 11, 2023 •

edited

Loading