Window: beforeunload event
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Thebeforeunload
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 theyreally 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 othertruthy 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 theonbeforeunload
property, not theaddEventListener()
method. This behavior is consistent across modern versions of Firefox, Safari, and Chrome.
The last two mechanisms are legacy features; best practice is to trigger the dialog by invokingpreventDefault()
on the event object, while also settingreturnValue
to support legacy cases.
Syntax
Use the event name in methods likeaddEventListener()
, or set an event handler property.
addEventListener("beforeunload", (event) => { })onbeforeunload = (event) => { }
Event type
ABeforeUnloadEvent
. Inherits fromEvent
.
Usage notes
To trigger the dialog being shown when the user closes or navigates the tab, abeforeunload
event handler function should callpreventDefault()
on the event object. You should note that modern implementations:
- Requiresticky 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.
Thebeforeunload
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:- A mobile user visits your page.
- The user then switches to a different app.
- 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. SeeDon't lose user and app state, use Page Visibility for more details.In Firefox,
beforeunload
is not compatible with theback/forward cache (bfcache): that is, Firefox will not place pages in the bfcache if they havebeforeunload
listeners, and this is bad for performance.
It is therefore recommended that developers listen forbeforeunload
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 forbeforeunload
sparingly can minimize the effect on performance.
Event handler aliases
In addition to theWindow
interface, the event handler propertyonbeforeunload
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:
<form> <input type="text" name="name" /></form>
Our JavaScript attaches aninput
event listener to the<input>
element that listens for changes in the inputted value. When the value is updated to a non-empty value, abeforeunload
event listener is attached to theWindow
object.
If the value becomes an empty string again (i.e., the value is deleted), thebeforeunload
event listener is removed again — as mentioned above in theUsage notes, the listener should be removed when there is no unsaved data to warn about.
Thebeforeunload
event handler function invokesevent.preventDefault()
to trigger the warning dialog when the user closes or navigates the tab. We have also includedevent.returnValue = true
in the handler function so that any browsers that don't support theevent.preventDefault()
mechanism will still run the demo correctly.
const beforeUnloadHandler = (event) => { // Recommended event.preventDefault(); // Included for legacy support, e.g. Chrome/Edge < 119 event.returnValue = true;};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
Specification |
---|
HTML # event-beforeunload |
HTML # handler-window-onbeforeunload |
Browser compatibility
See also
BeforeUnloadEvent
interface- Related events:
- Page Lifecycle API provides more useful guidance on handling page lifecycle behavior in your web apps.