Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Events

The beforeunload event

Reference for the beforeunload event: ask the browser to confirm before closing or leaving a page with unsaved changes, and why you must add the listener sparingly.

The beforeunload event fires on window just before the page is unloaded: when the user closes the tab, reloads, types a new address or follows a link. If a listener asks for it, the browser shows a confirmation dialog ("Leave site? Changes you made may not be saved.") and the user decides whether to stay or leave.

Its one good use is protecting unsaved work. Add the listener when the form becomes dirty and remove it when it is saved. Do not use it to run analytics or cleanup, and do not show it all the time: it makes the page ineligible for the back/forward cache in some browsers, and users find constant prompts hostile.

JavaScript
function warn(event) {
  event.preventDefault();
  event.returnValue = "";   // older browsers need this
}

window.addEventListener("beforeunload", warn);   // when the form is dirty
window.removeEventListener("beforeunload", warn); // after saving

Try it

Protect unsaved changes

Syntax

JavaScript
window.addEventListener("beforeunload", (event) => {
  event.preventDefault();
  event.returnValue = "";
});

window.onbeforeunload = (event) => { /* legacy form */ };

The event is a BeforeUnloadEvent and is cancelable. Calling event.preventDefault() is the standard way to request the prompt. Setting event.returnValue to a string (even an empty one) is the older way, still needed by some browsers, so use both.

Usage notes

  • You cannot customize the message. Browsers ignore any text you provide and show their own generic wording, to prevent scare tactics.
  • The prompt needs a user gesture. Browsers show it only if the user has interacted with the page (clicked, typed). A page the user never touched can be left without a prompt.
  • No blocking code. Calls such as alert(), confirm() and prompt() are ignored inside the handler. Do not start slow work; the page is about to go away.
  • Cannot detect the choice. If the user presses Cancel, nothing is fired; if they leave, the page just unloads. If you need to know when the page actually goes away, use pagehide.
  • Do not use it for analytics. It does not fire reliably on mobile browsers (for example when the user swipes the app away). Send data on visibilitychange with navigator.sendBeacon() or fetch(url, { keepalive: true }).
  • Add it only when needed. Adding a beforeunload listener can stop the browser from putting the page in the back/forward cache, which makes back navigation slower. Register it while there is unsaved data and remove it afterwards.
  • Frames. Browsers may ignore the prompt in subframes, so do not depend on it inside an iframe.
  • In-app navigation is not covered. A single-page app changing routes with history.pushState() does not unload the page, so you need your own check in the router.

Browser support

beforeunload with preventDefault() or returnValue works in all current browsers, though the dialog text and the conditions for showing it differ. Treat it as a safety net, not as a guarantee.