W3cubDocs

/Web APIs

Window: beforeunload event

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

The main use case for this event is to trigger a browser-generated confirmation dialog that asks users to confirm if they really want to leave the page when they try to close or reload it, or navigate somewhere else. This is intended to help prevent loss of unsaved data.

The dialog can be triggered in the following ways:

  • Calling the event object's preventDefault() method.
  • Setting the event object's returnValue property to a non-empty string value or any other truthy value.
  • Returning any truthy value from the event handler function, e.g. return "string". Note that this only works when the function is attached via the onbeforeunload property, not the addEventListener() method. This behavior is consistent across modern versions of Firefox, Safari, and Chrome.

The last two machanisms are legacy features; best practice is to trigger the dialog by invoking preventDefault() on the event object.

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.

Usage notes

To trigger the dialog being shown when the user closes or navigates the tab, a beforeunload event handler function should call preventDefault() on the event object. You should note that modern implementations:

  • Require sticky activation for the dialog to be displayed. In other words, the browser will only show the dialog box if the frame or any embedded frame receives a user gesture or user interaction. 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.
  • Only show a generic browser-specified string in the displayed dialog. This cannot be controlled by the webpage code.

The beforeunload event suffers from some problems:

  • It is not reliably fired, especially on mobile platforms. 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.

    Note: It is recommended to use the visibilitychange event as a more reliable signal for automatic app state saving that gets around problems like the above. See Don't lose user and app state, use Page Visibility for more details.

  • In Firefox, beforeunload 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.

It is therefore recommended that developers listen for beforeunload only when users have unsaved changes so that the dialog mentioned above can be used to warn them about impending data loss, and remove the listener again when it is not needed. Listening for beforeunload sparingly can minimize the effect on performance.

Event handler aliases

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

Examples

In the following example we have an HTML text <input> to represent some data that could be changed and require saving:

html

<form>
  <input type="text" name="name" id="name" />
</form>

Our JavaScript attaches an input event listener to the <input> element that listens for changes in the inputted value. When the value is updated to a non-empty value, a beforeunload event listener is attached to the Window object.

If the value becomes an empty string again (i.e. the value is deleted), the beforeunload event listener is removed again — as mentioned above in the Usage notes, the listener should be removed when there is no unsaved data to warn about.

The beforeunload event handler function invokes preventDefault() to trigger the warning dialog when the user closes or navigates the tab.

js

const beforeUnloadHandler = (event) => {
  event.preventDefault();
  // Equivalent to the following legacy mechanisms
  //   event.returnValue = "string";
  //   return "string"; (only works with onbeforeunload)
};

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

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

When the <input> value is non-empty, if you try to close, navigate, or reload the page the browser displays the warning dialog. Try it out:

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
beforeunload_event 1 12 1 4 12 3 4.4 18 4 12 1 1.0
event_returnvalue_activation 119
30–119Before Chrome 119, an empty string incorrectly activated the confirmation dialog.
119
79–119Before Edge 119, an empty string incorrectly activated the confirmation dialog.
6 9
17Before Opera false, an empty string incorrectly activated the confirmation dialog.
8
4.4Before Chrome 119, an empty string incorrectly activated the confirmation dialog.
119
30–119Before Chrome 119, an empty string incorrectly activated the confirmation dialog.
6
18Before Opera false, an empty string incorrectly activated the confirmation dialog.
No
2.0Before Samsung Internet false, an empty string incorrectly activated the confirmation dialog.
generic_string_displayed 51 12 44 11 38 9.1 51 51 44 41 9.3 5.0
preventdefault_activation 119 11912–79 6 9 No 11 No 119 6 No No No
return_string_activation 1 12 1 9 12 3 4.4 18 4 12 No 1.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event