jQuery .unload() Method

What You’ll Learn

The .unload() method was jQuery’s shorthand for binding to the browser’s unload event — typically on window to run cleanup when a page closes. Deprecated in 1.8 and removed in 3.0, it appears often in legacy themes. This tutorial covers bind, trigger, and eventData forms from the official API, migration to .on(), modern lifecycle alternatives, and five try-it examples.

Introduction

Before single-page apps and modern lifecycle APIs, developers attached handlers to the browser unload event to save drafts, flush analytics, or tear down widgets when the user navigated away. jQuery wrapped that pattern in a one-line shorthand: $(window).unload(handler).

Available since jQuery 1.0, .unload() accepted a handler function, optional eventData (since 1.4.3), or no arguments to programmatically trigger bound handlers. It was deprecated in 1.8 alongside .load() and .error() event shorthands, then removed entirely in jQuery 3.0.

Do not use .unload() in new code. Replace it with .on("unload", handler) when maintaining legacy behavior, or prefer pagehide and visibilitychange for reliable page-lifecycle handling. Browse the Event Handler hub for modern .on() and .off() tutorials.

Understanding the .unload() Method

.unload( handler ) attached a function to the unload event on each matched element. On window, the handler ran when the document or a child resource was being unloaded — closing the tab, navigating away, or refreshing. .unload() with no arguments called every bound unload handler without a native browser navigation.

Like other legacy shorthands, .unload() was sugar over .bind("unload", handler) and .trigger("unload"). It could not delegate events and shared its name with unrelated Ajax APIs, which contributed to its removal.

📝 Syntax

Three signatures from the official jQuery API (deprecated 1.8, removed 3.0):

1. Bind handler — .unload( handler ) since 1.0

.unload( handler )

• handler — function executed each time the unload event fires.
• Most commonly used on $(window).

2. Bind with eventData — .unload( [eventData], handler ) since 1.4.3

$( window ).unload( { app: "myApp" }, function( event ) {
  console.log( event.data.app );  // "myApp"
});

3. Trigger handlers — .unload() since 1.0

$( window ).unload();  // fire bound unload handlers

Migration to .on() / .trigger()

// Legacy (jQuery 1.x–2.x)
$( window ).unload( handler );
$( window ).unload( { app: "myApp" }, handler );
$( window ).unload();

// jQuery 3.x+ replacement
$( window ).on( "unload", handler );
$( window ).on( "unload", { app: "myApp" }, handler );
$( window ).trigger( "unload" );

// Modern lifecycle (recommended for new code)
$( window ).on( "pagehide", handler );
$( document ).on( "visibilitychange", function() {
  if ( document.visibilityState === "hidden" ) { /* cleanup */ }
});

Return value

• Returns the jQuery object for chaining.
• Handler binding forms return the collection; trigger form returns after handlers run.

Examples Gallery

Examples 1–3 follow the official jQuery API signatures for .unload(). Examples 4–5 cover migration to .on() and modern lifecycle events. Try-it labs 1–3 load jQuery 2.2.4; labs 4–5 use jQuery 3.7.

$( window ).unload( function() {
  // Legacy cleanup — runs on page exit
  sessionStorage.setItem( "lastVisit", Date.now() );
});

Handler attached with .unload(fn)
Try-it simulates with .trigger("unload") — real unload fires on navigation

sessionStorage updated on simulated unload

$( window ).unload( { appId: "dashboard" }, function( event ) {
  console.log( "Cleaning up:", event.data.appId );
});

On trigger: logs "Cleaning up: dashboard"
event.data.appId === "dashboard"

Same eventData pattern as .on("unload", data, fn)

$( window ).unload( function() {
  $( "#log" ).append( "<p>Unload handler ran</p>" );
});

// Later — test or simulate page exit
$( window ).unload();

Click "Simulate unload" → $(window).unload() runs handlers
#log shows "Unload handler ran"

Modern equivalent: $(window).trigger("unload")

// Before (jQuery 2.x)
// $( window ).unload( cleanup );

// After (jQuery 3.x+)
$( window ).on( "unload", cleanup );

function cleanup() {
  localStorage.setItem( "draftSaved", "true" );
}

// Remove when done
$( window ).off( "unload", cleanup );

.on("unload", cleanup) binds in jQuery 3.7
.trigger("unload") runs cleanup
.off("unload", cleanup) removes handler

Minimal search-and-replace migration from .unload()

$( window ).on( "pagehide", function( event ) {
  // Runs when page enters bfcache or unloads — more reliable than unload
  if ( event.originalEvent.persisted ) {
    console.log( "Page cached — lightweight pause" );
  } else {
    console.log( "Page leaving — run cleanup" );
  }
});

pagehide fires more reliably than unload
event.originalEvent.persisted === true when bfcache stores page

Recommended for analytics flush and session cleanup in new apps

🚀 Common Use Cases (Legacy)

• Analytics flush — send a beacon when the user navigates away (prefer pagehide today).
• Draft autosave — persist form state on page exit (consider visibilitychange for tab switches).
• Widget teardown — destroy plugins and timers when leaving a single-page section.
• Session logging — record last-visit timestamps in sessionStorage.
• Legacy maintenance — read old .unload() calls in jQuery 1.x/2.x themes during upgrades.
• Migration audits — grep for .unload( and replace with .on("unload" or lifecycle alternatives.

📝 Notes

• Deprecated in jQuery 1.8; removed in jQuery 3.0 alongside .load() and .error() event shorthands.
• Conflicted with Ajax .load(url) — a major reason for removal.
• The native unload event is also discouraged by browser vendors.
• Long-running unload handlers block navigation and hurt user experience.
• Use beforeunload only for unsaved-change confirmation dialogs.
• Try-it labs 1–3 require jQuery 2.2.4 to call .unload() directly.
• Search legacy code: .unload(, bind("unload", and onunload=.

💡 Best Practices