Window: pageshow — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("pageshow", handler)

Beschreibung

Das pageshow-Event wird an window gesendet, wenn der Browser ein Dokument anzeigt. Das passiert beim ersten Laden der Seite (dann nach dem load-Event) und auch dann, wenn der Nutzer per Zurück- oder Vorwärts-Schaltfläche zu einer Seite zurückkehrt, die im Back/Forward-Cache (bfcache) gespeichert war.

Der Handler bekommt ein PageTransitionEvent. Die wichtigste Eigenschaft ist event.persisted: Ist sie true, wurde die Seite aus dem bfcache wiederhergestellt. In diesem Fall läuft kein load- und kein DOMContentLoaded-Event erneut – Skripte werden nicht neu ausgeführt, und der JavaScript-Zustand ist genau so, wie er beim Verlassen war.

Deshalb ist pageshow die richtige Stelle, um veraltete Daten zu aktualisieren (z. B. Warenkorb, Login-Status), Verbindungen wie WebSockets neu aufzubauen, Timer neu zu starten oder Analytics-Seitenaufrufe für wiederhergestellte Seiten zu zählen. Das Gegenstück ist pagehide, das beim Verlassen einer Seite ausgelöst wird.

Registriert wird der Handler mit window.addEventListener("pageshow", handler) oder über die Eigenschaft window.onpageshow = handler (auch als Attribut <body onpageshow="..."> möglich).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Event-Name `"pageshow"`.
$handler Pflicht	(event: PageTransitionEvent) => void		Callback, der ein `PageTransitionEvent` erhält. `event.persisted` ist `true`, wenn die Seite aus dem bfcache stammt.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Event ist nicht abbrechbar (cancelable: false).

Beispiele

Wiederherstellung aus dem bfcache erkennen

window.addEventListener("pageshow", (event) => {
  if (event.persisted) {
    console.log("Seite aus dem bfcache wiederhergestellt");
  } else {
    console.log("Seite normal geladen");
  }
});

Seite normal geladen // nach Zurück-Navigation: Seite aus dem bfcache wiederhergestellt

Veraltete Daten nach Zurück-Navigation aktualisieren

const updateCartBadge = async () => {
  const res = await fetch("/api/cart/count");
  const { count } = await res.json();
  document.querySelector("#cart-badge").textContent = count;
};

window.addEventListener("pageshow", (event) => {
  // Beim normalen Laden erledigt das bereits der Initialcode
  if (event.persisted) {
    updateCartBadge();
  }
});

WebSocket mit pagehide/pageshow schließen und neu öffnen

let socket = null;

const connect = () => {
  socket = new WebSocket("wss://example.com/live");
  socket.addEventListener("open", () => console.log("verbunden"));
};

connect();

// Offene WebSockets verhindern in vielen Browsern den bfcache
window.addEventListener("pagehide", () => {
  socket?.close();
});

window.addEventListener("pageshow", (event) => {
  if (event.persisted) connect();
});

verbunden

Über die on-Property registrieren und wieder entfernen

window.onpageshow = (event) => {
  console.log("pageshow, persisted =", event.persisted);
};

// Handler wieder entfernen
window.onpageshow = null;

// Alternative mit removeEventListener
const onShow = (e) => console.log("angezeigt", e.persisted);
window.addEventListener("pageshow", onShow);
window.removeEventListener("pageshow", onShow);

// Wichtig · Fallstricke

Kein erneutes load: Bei Wiederherstellung aus dem bfcache laufen load und DOMContentLoaded nicht noch einmal. Wer Aktualisierungen nur in load macht, zeigt veraltete Daten an.
Beim ersten Laden kommt es nach load: Wird der Listener erst nach dem load-Event registriert (z. B. lazy nachgeladene Skripte), verpasst man das initiale pageshow.
bfcache-Blockierer: unload-Handler, offene WebSocket-/IndexedDB-Verbindungen oder Cache-Control: no-store können verhindern, dass eine Seite im bfcache landet – dann ist persisted immer false. Statt unload besser pagehide nutzen.
Das Event wird nur an window gesendet, bubbelt nicht und ist nicht abbrechbar.
Kompatibilität: In allen modernen Browsern verfügbar. Das Verhalten des bfcache unterscheidet sich jedoch je nach Browser (Chrome, Firefox, Safari haben unterschiedliche Ausschlussregeln). Chrome DevTools bieten unter „Application → Back/forward cache“ einen Test.

Siehe auch

HID: connect Window: pageswap Window: pagehide Window: error Window: pagereveal