WindowEventHandlers.onbeforeunload

The WindowEventHandlers.onbeforeunload event handler property contains the code executed when the beforeunload is sent. This event fires when a window is about to unload its resources. The document is still visible and the event is still cancelable.

Syntax

window.onbeforeunload = funcRef

• funcRef is a reference to a function or a function expression.
• 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.

Example

window.addEventListener('beforeunload', function (e) {
  // Cancel the event as stated by the standard.
  e.preventDefault();
  // Chrome requires returnValue to be set.
  e.returnValue = '';
});

Notes

When this event returns (or sets the returnValue property to) a value other than null or undefined, the user is prompted to confirm the page unload. In some browsers, the return value of the event is displayed in this dialog. Starting with Firefox 44, Chrome 51, Opera 38 and Safari 9.1, a generic string not under the control of the webpage will be 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 bug 588292), and Chrome displays the string "Do you want to leave this site? Changes you made may not be saved" (see Chrome Platform Status).

Internet Explorer does not respect the null return value and will display this to users as "null" text. You have to use undefined to skip the prompt.

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.

Note also, that various browsers ignore the result of the event and do not ask the user for confirmation at all. The document will always be unloaded automatically. Firefox has a switch named dom.disable_beforeunload in about:config to enable this behaviour.

You can and should handle this event through window.addEventListener() and the beforeunload event. More documentation is available there.

Binding to this event can be used to prevent the browser from fully caching the page in cases where content is rendered by javascript. In certain circumstances when returning to a page that has executed javascript in order to populate content, you may find the javascript not running upon the return visit when navigating back. If window.onbeforeunload has been bound (and thus triggered when leaving that page) javascript in the page will be triggered on the subsequent return visit and therefore update the content.

Specifications

The event was originally introduced by Microsoft in Internet Explorer 4 and standardized in the HTML5 specification.

Browser compatibilityUpdate compatibility data on GitHub