BeforeUnloadEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface BeforeUnloadEvent extends Event

Beschreibung

BeforeUnloadEvent ist das Ereignisobjekt, das an Handler des beforeunload-Events am window übergeben wird. Das Event wird ausgelöst, kurz bevor das Fenster, das Dokument und die zugehörigen Ressourcen entladen werden – etwa beim Schließen des Tabs, beim Neuladen oder beim Wechsel zu einer anderen URL. Zu diesem Zeitpunkt ist das Dokument noch sichtbar, und das Entladen lässt sich noch abbrechen.

Wichtigster Einsatzzweck: Nutzer vor dem Verlust ungespeicherter Daten warnen (Formulare, Editoren, laufende Uploads). Ruft der Handler event.preventDefault() auf (oder setzt – veraltet – event.returnValue auf einen nicht leeren String), zeigt der Browser einen eigenen Bestätigungsdialog an. Den Text dieses Dialogs kann man aus Sicherheitsgründen nicht selbst festlegen; moderne Browser zeigen immer einen allgemeinen Standardtext.

Das Interface erbt alle Eigenschaften und Methoden von Event. Zusätzlich gibt es die Eigenschaft returnValue (String), die aus historischen Gründen weiterhin unterstützt wird. Der Handler sollte nur bedingt registriert werden – also nur dann, wenn tatsächlich ungesicherte Änderungen vorliegen – und danach wieder entfernt werden.

Parameter

Name	Typ	Default	Beschreibung
$returnValue	string	""	Veraltete Eigenschaft. Ein nicht leerer String signalisiert dem Browser, dass ein Bestätigungsdialog angezeigt werden soll. Der Inhalt selbst wird nicht angezeigt.
$preventDefault()	function		Empfohlener, standardkonformer Weg, den Bestätigungsdialog anzufordern (geerbt von `Event`).

Rückgabewert

Typ

BeforeUnloadEvent

Beschreibung

Das Ereignisobjekt wird vom Browser erzeugt und an den beforeunload-Handler übergeben; ein eigener Konstruktor ist nicht vorgesehen.

Beispiele

Warnung bei ungespeicherten Formulardaten (addEventListener)

const form = document.querySelector('#profil-form');

const beforeUnloadHandler = (event) => {
  // Standardkonform: Dialog anfordern
  event.preventDefault();
  // Fallback für ältere Browser
  event.returnValue = '';
};

// Handler nur registrieren, wenn tatsächlich etwas geändert wurde
form.addEventListener('input', () => {
  window.addEventListener('beforeunload', beforeUnloadHandler);
}, { once: true });

// Nach erfolgreichem Speichern wieder entfernen
form.addEventListener('submit', () => {
  window.removeEventListener('beforeunload', beforeUnloadHandler);
});

Beim Schließen des Tabs nach einer Eingabe zeigt der Browser seinen Standard-Bestätigungsdialog.

Zustandsgesteuerter Schutz in einem Editor

let hasUnsavedChanges = false;

const guard = (event) => {
  if (!hasUnsavedChanges) return;
  event.preventDefault();
  event.returnValue = '';
};

const setDirty = (dirty) => {
  hasUnsavedChanges = dirty;
  if (dirty) {
    window.addEventListener('beforeunload', guard);
  } else {
    window.removeEventListener('beforeunload', guard);
  }
};

document.querySelector('#editor').addEventListener('input', () => setDirty(true));

const save = async () => {
  await fetch('/api/dokument', { method: 'PUT', body: 'Inhalt' });
  setDirty(false);
  console.log('Gespeichert – Seite kann ohne Warnung verlassen werden');
};

Gespeichert – Seite kann ohne Warnung verlassen werden

Variante mit der on-Property window.onbeforeunload

window.onbeforeunload = (event) => {
  console.log(event instanceof BeforeUnloadEvent);
  event.preventDefault();
  // Historisch: Rückgabe eines Strings löst ebenfalls den Dialog aus
  return '';
};

// Schutz später deaktivieren
const disableGuard = () => {
  window.onbeforeunload = null;
};

true

// Wichtig · Fallstricke

Kein eigener Text: Chrome, Firefox und Safari ignorieren eigene Meldungen in returnValue oder im Rückgabewert und zeigen einen festen Standardtext.
Nutzerinteraktion nötig: Der Dialog erscheint nur, wenn der Nutzer vorher mit der Seite interagiert hat (Sticky Activation). Ohne Interaktion wird er stillschweigend unterdrückt.
Kompatibilität: preventDefault() löst den Dialog in Chrome/Edge erst ab Version 119 aus. Für ältere Browser zusätzlich event.returnValue = '' setzen.
Back/Forward-Cache: Ein registrierter beforeunload-Handler kann in manchen Browsern (v. a. Firefox) verhindern, dass die Seite in den bfcache kommt. Deshalb den Handler nur bei Bedarf hinzufügen und danach wieder entfernen.
Nicht zuverlässig auf Mobilgeräten: Beim Wechsel der App oder beim Beenden durch das Betriebssystem wird das Event oft nicht ausgelöst. Zum Sichern von Daten besser visibilitychange (Zustand hidden) zusammen mit navigator.sendBeacon() verwenden.
Im Handler sind alert(), confirm() und prompt() blockiert; auch lange synchrone Arbeit oder asynchrone Anfragen, auf deren Ende man wartet, sind hier fehl am Platz.
Die Warnung nicht zum Festhalten von Nutzern missbrauchen – Browser schränken das Verhalten genau deshalb immer weiter ein.

Siehe auch

Event.prototype.preventDefault() Navigator.prototype.sendBeacon() Event FormDataEvent SensorErrorEvent