Window: unload — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("unload", handler)

Beschreibung

Das unload-Ereignis tritt am Window auf, wenn ein Dokument entladen wird, etwa beim Navigieren zu einer anderen Seite, beim Schließen des Tabs oder beim Neuladen. Es kommt nach beforeunload und pagehide. Zu diesem Zeitpunkt ist das Dokument noch da, aber nicht mehr sichtbar und nicht mehr bedienbar. Das Ereignis lässt sich nicht abbrechen und es steigt nicht im DOM auf (kein Bubbling).

Registrieren kannst du einen Handler mit window.addEventListener("unload", handler) oder über die Eigenschaft window.onunload = handler. Der Handler bekommt ein einfaches Event-Objekt.

Wichtig: Das Ereignis gilt heute als veraltet. Es wird nicht zuverlässig ausgelöst. Auf Mobilgeräten fällt es oft ganz aus, zum Beispiel wenn der Nutzer die App wechselt und das Betriebssystem den Tab danach beendet. Außerdem verhindert ein registrierter unload-Handler, dass die Seite im Back/Forward-Cache (bfcache) gespeichert wird. Dadurch wird das Zurück-Navigieren spürbar langsamer.

Für neuen Code gilt: pagehide nehmen, wenn du auf das Verlassen der Seite reagieren willst. visibilitychange mit document.visibilityState === "hidden" nehmen, wenn du Zustand speichern oder Analysedaten verschicken willst. Für das Senden von Daten eignen sich navigator.sendBeacon() oder fetch() mit keepalive: true.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"unload"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Entladen aufgerufen wird. Er bekommt ein einfaches `Event`-Objekt (nicht abbrechbar, kein Bubbling).
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen für `addEventListener`, z. B. `{ once: true }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Was der Handler zurückgibt, wird ignoriert.

Beispiele

Legacy-Handler mit addEventListener und removeEventListener

// Nur zur Veranschaulichung – blockiert den bfcache!
const onUnload = () => {
  console.log('Seite wird entladen');
};

window.addEventListener('unload', onUnload);

// Handler später wieder entfernen, damit der bfcache wieder genutzt werden kann
window.removeEventListener('unload', onUnload);

Über die on-Property registrieren und wieder entfernen

window.onunload = (event) => {
  console.log(event.type, event.cancelable); // unload false
};

// Entfernen:
window.onunload = null;

unload false

Moderne Alternative: pagehide + sendBeacon

const sendAnalytics = () => {
  const payload = JSON.stringify({ path: location.pathname, t: Date.now() });
  navigator.sendBeacon('/api/analytics', payload);
};

// pagehide blockiert den bfcache nicht
window.addEventListener('pagehide', (event) => {
  console.log('persisted (bfcache):', event.persisted);
  sendAnalytics();
});

persisted (bfcache): true

Zustand zuverlässig sichern mit visibilitychange

const saveDraft = () => {
  const text = document.querySelector('#editor')?.value ?? '';
  localStorage.setItem('draft', text);
};

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    saveDraft();
  }
});

// Wichtig · Fallstricke

Veraltet: Chrome baut unload schrittweise ab. Die Permissions-Policy unload kann die Handler ganz abschalten (Header Permissions-Policy: unload=()). Firefox und Safari lösen das Ereignis weiterhin aus, aber nicht zuverlässig.
Unzuverlässig: Auf Mobilgeräten und bei abstürzenden oder vom System beendeten Tabs wird es oft gar nicht ausgelöst. Kritische Daten deshalb nie nur hier speichern.
bfcache: Ein registrierter unload-Handler verhindert in vielen Browsern, dass die Seite im Back/Forward-Cache landet. Das verschlechtert die Performance beim Zurück-Navigieren.
Eingeschränkt: alert(), confirm(), prompt() und window.open() werden im Handler ignoriert. Synchrones XMLHttpRequest ist in modernen Browsern hier verboten. Asynchrone fetch-Anfragen ohne keepalive werden meist abgebrochen.
Abbrechen nicht möglich: Um das Verlassen der Seite zu bestätigen, beforeunload verwenden.
In iframes wird unload auch ausgelöst, wenn das Elterndokument entladen wird. Die Reihenfolge ist: erst das Elterndokument, dann die Kind-Frames.

Siehe auch

Window: pagehide Window: beforeunload Document: visibilitychange Window: load Navigator.sendBeacon() Element: wheel