jQuery Unload Event

What You’ll Learn

The unload event fires on window when the user leaves the page. jQuery binds it with .on("unload", handler) and triggers it with .trigger("unload"). This tutorial covers official API patterns, cleanup use cases, comparisons with beforeunload and pagehide, the removed .unload() shorthand, and five interactive try-it examples.

Introduction

When a user clicks a link, types a new URL, presses back or forward, closes the tab, or reloads the page, the browser begins unloading the current document. jQuery exposes this lifecycle moment as the unload event on window.

Scripts historically used unload handlers for last-chance cleanup — flushing analytics, saving draft state, or tearing down timers. Bind with $(window).on("unload", handler) since jQuery 1.7, optionally pass eventData, and remove handlers with .off("unload", handler).

Browser vendors now discourage relying on unload because it is unreliable on mobile and harms back/forward cache performance. For new code, consider pagehide or visibilitychange. This page documents the official jQuery unload event API for learning and legacy maintenance. For the removed .unload() shorthand, see the .unload() tutorial.

Understanding the unload Event

The unload event is sent to the window element when navigation away from the page begins. It can fire on link navigation, address bar changes, history traversal, tab close, and page reload (reload triggers unload before the new load). Exact timing varies slightly between browsers — always test supported targets.

Handlers exist so scripts can perform cleanup. Most browsers ignore alert(), confirm(), and prompt() inside unload handlers. A returned string may appear in a confirmation dialog on some browsers, but this is inconsistent — use beforeunload for leave warnings. You cannot cancel navigation with event.preventDefault() on unload.

📝 Syntax

The modern jQuery API for the unload event has two main forms:

1. Bind a handler — .on("unload" [, eventData ], handler) (since 1.7)

.on( "unload" [, eventData ], handler )

• eventData — optional object available as event.data in the handler.
• handler — function( event ) { ... } run when the page unloads.
• Bind on $(window) per the official jQuery documentation.

2. Trigger the event — .trigger("unload") (since 1.0)

.trigger( "unload" )

• Runs bound unload handlers without a real browser navigation.
• Useful for unit tests and interactive demos.

3. Unbind — .off("unload" [, handler])

$( window ).off( "unload" );              // remove all unload handlers
$( window ).off( "unload", cleanup );     // remove specific handler

Official jQuery API examples

$( window ).on( "unload", function() {
  return "Handler for `unload` called.";
} );

// To display a message when the page is unloaded:
$( window ).on( "unload", function() {
  return "Bye now!";
} );

Return value

• .on() and .trigger() return the jQuery object for chaining.
• Inside the handler, this refers to the window DOM object.

Examples Gallery

Examples 1–3 follow the official jQuery API documentation. Examples 4–5 extend the pattern with session cleanup and a pagehide alternative. Use the Try-it links to run each snippet in the browser.

$( window ).on( "unload", function() {
  return "Handler for `unload` called.";
} );

Handler bound on window

On real navigation: unload fires during page exit
Try-it: trigger("unload") runs handler and logs message

Return value may show in dialog on some browsers — not guaranteed

$( window ).on( "unload", function() {
  return "Bye now!";
} );

Handler returns "Bye now!" string

Browsers may ignore alert/confirm/prompt in unload handlers
Use beforeunload for intentional leave dialogs

$( window ).on( "unload", function() {
  $( "#log" ).text( "Handler for unload called." );
} );

$( "#other" ).on( "click", function() {
  $( window ).trigger( "unload" );
} );

Click #other → trigger("unload") on window

#log shows: Handler for unload called.

Does not navigate away — only runs jQuery-bound handlers

$( window ).on( "unload", { app: "editor" }, function( event ) {
  sessionStorage.setItem(
    event.data.app + ":lastExit",
    Date.now()
  );
} );

event.data.app === "editor"
sessionStorage key editor:lastExit set to timestamp

Keep unload handlers fast — long sync work may be killed by browser

// Recommended for new projects instead of unload
$( window ).on( "pagehide", function( event ) {
  if ( event.originalEvent && event.originalEvent.persisted ) {
    console.log( "Page entering bfcache" );
  } else {
    console.log( "Page leaving — run cleanup" );
    navigator.sendBeacon( "/analytics", "exit" );
  }
} );

pagehide fires when tab hidden or page navigated away
event.originalEvent.persisted === true when bfcache stores page

sendBeacon works well for analytics flush on exit

🚀 Common Use Cases

• Analytics beacons — flush pending events when the user leaves (prefer sendBeacon with pagehide).
• Draft persistence — write form state to sessionStorage on exit.
• Timer teardown — clear intervals tied to the page lifecycle.
• Legacy maintenance — read existing .on("unload") handlers during jQuery upgrades.
• Testing — use .trigger("unload") to verify cleanup logic in isolation.
• Migration — replace removed .unload(fn) with .on("unload", fn).

📝 Notes

• Bind handlers on $(window) — official jQuery requirement.
• .on("unload") available since jQuery 1.7; .trigger("unload") since 1.0.
• Cannot cancel navigation with event.preventDefault() on unload.
• Most browsers ignore alert/confirm/prompt inside unload handlers.
• Reload triggers unload before the new page load begins.
• Mobile browsers may not fire unload reliably — test on real devices.
• Legacy shorthand: .unload() removed in jQuery 3.0 — see dedicated tutorial.

💡 Best Practices