Window: beforeunload event

The beforeunload event is fired when the window, the document and its resources are about to be unloaded. The document is still visible and the event is still cancelable at this point.

This event enables a web page to trigger a confirmation dialog asking the user if they really want to leave the page. If the user confirms, the browser navigates to the new page, otherwise it cancels the navigation.

According to the specification, to show the confirmation dialog an event handler should call preventDefault() on the event.

The HTML specification states that calls to window.alert(), window.confirm(), and window.prompt() methods may be ignored during this event. See the HTML specification for more details.

Syntax

Use the event name in methods like addEventListener(), or set an event handler property.

js

addEventListener("beforeunload", (event) => {});
onbeforeunload = (event) => {};

Event type

A BeforeUnloadEvent. Inherits from Event.

Event handler aliases

In addition to the Window interface, the event handler property onbeforeunload is also available on the following targets:

Security

Sticky activation is required. The user has to have interacted with the page in order for this feature to work.

Usage notes

The beforeunload event suffers from the same problems as the unload event.

Especially on mobile, the beforeunload event is not reliably fired. For example, the beforeunload event is not fired at all in the following scenario:

  1. A mobile user visits your page.
  2. The user then switches to a different app.
  3. Later, the user closes the browser from the app manager.

Additionally, on Firefox, the beforeunload event is not compatible with the back/forward cache (bfcache): that is, Firefox will not place pages in the bfcache if they have beforeunload listeners, and this is bad for performance.

However, unlike the unload event, there is a legitimate use case for the beforeunload event: the scenario where the user has entered unsaved data that will be lost if the page is unloaded.

It is recommended that developers listen for beforeunload only in this scenario, and only when they actually have unsaved changes, so as to minimize the effect on performance. See the Examples section below for an example of this.

See the bfcache guide on web.dev for more information about the problems associated with the beforeunload event.

Examples

In this example a page listens for changes to a text input. If the element contains a value, it adds a listener for beforeunload. If the element is empty, it removes the listener:

js

const beforeUnloadListener = (event) => {
  event.preventDefault();
  return (event.returnValue = "");
};

const nameInput = document.querySelector("#name");

nameInput.addEventListener("input", (event) => {
  if (event.target.value !== "") {
    addEventListener("beforeunload", beforeUnloadListener, { capture: true });
  } else {
    removeEventListener("beforeunload", beforeUnloadListener, {
      capture: true,
    });
  }
});

Specifications

Specification
HTML Standard
# event-beforeunload
HTML Standard
# handler-window-onbeforeunload

Browser compatibility

BCD tables only load in the browser

Compatibility notes

The HTML specification states that authors should use the Event.preventDefault() method instead of using Event.returnValue to prompt the user. However, this is not yet supported by all browsers.

When this event returns (or sets the returnValue property to) a value other than null or undefined, the user will be prompted to confirm the page unload. In older browsers, the return value of the event is displayed in this dialog. Since Firefox 44, Chrome 51, Opera 38, and Safari 9.1, a generic string not under the control of the webpage is shown instead of the returned string. For example:

  • Firefox displays the string, "This page is asking you to confirm that you want to leave - data you have entered may not be saved." (see Firefox bug 588292).
  • Chrome displays the string, "Do you want to leave the site? Changes you made may not be saved." (see Chrome Platform Status).

In some browsers, calls to window.alert(), window.confirm(), and window.prompt() may be ignored during this event. See the HTML specification for more details.

Note also, that various browsers ignore the result of the event and do not ask the user for confirmation at all. In such cases, the document will always be unloaded automatically. Firefox has a switch named dom.disable_beforeunload in about:config to enable this behavior. As of Chrome 60, the confirmation will be skipped if the user has not performed a gesture in the frame or page since it was loaded. Pressing F5 in the page seems to count as user interaction, whereas mouse-clicking the refresh arrow or pressing F5 with Chrome DevTools focused does not count as user interaction (as of Chrome 81).

See also