PopStateEvent.state — Eigenschaft · JavaScript-Referenz

Signatur

PopStateEvent.state

Beschreibung

PopStateEvent.state liefert das Zustandsobjekt, das zuvor mit history.pushState() oder history.replaceState() an einen History-Eintrag gebunden wurde. Der Browser löst das popstate-Event aus, wenn der Nutzer mit den Vor- oder Zurück-Schaltflächen navigiert oder wenn history.back(), history.forward() bzw. history.go() aufgerufen wird. Die Eigenschaft enthält dann den Zustand des Eintrags, zu dem gewechselt wurde.

Die Eigenschaft ist vor allem für Single-Page-Applications wichtig: Statt die Seite neu zu laden, rekonstruiert die Anwendung die Ansicht anhand von event.state – zum Beispiel die aktive Registerkarte, Filtereinstellungen oder die Scrollposition.

Der Wert ist eine strukturierte Kopie (Structured Clone) des ursprünglich übergebenen Objekts, nicht dasselbe Objekt. Für Einträge ohne gespeicherten Zustand, zum Beispiel den ersten Seitenaufruf oder reine Hash-Navigationen (#anker), ist state gleich null.

Rückgabewert

Typ

any

Beschreibung

Eine strukturierte Kopie des Zustandsobjekts, das mit pushState()/replaceState() hinterlegt oder dem Konstruktor new PopStateEvent() übergeben wurde, oder null, wenn kein Zustand vorhanden ist.

Beispiele

Zustand bei Zurück-Navigation auslesen (addEventListener)

const render = (state) => {
  const view = state?.view ?? 'start';
  document.title = `Ansicht: ${view}`;
  console.log('Aktive Ansicht:', view);
};

const onPopState = (event) => {
  render(event.state);
};

window.addEventListener('popstate', onPopState);

// Neue Einträge anlegen
history.pushState({ view: 'produkte' }, '', '/produkte');
history.pushState({ view: 'warenkorb' }, '', '/warenkorb');

// Zurück navigieren → popstate wird asynchron ausgelöst
history.back();

// Später aufräumen:
// window.removeEventListener('popstate', onPopState);

Aktive Ansicht: produkte

Filterzustand einer Liste per onpopstate wiederherstellen

const applyFilter = ({ kategorie = 'alle', seite = 1 } = {}) => {
  console.log(`Zeige Kategorie "${kategorie}", Seite ${seite}`);
};

const setFilter = (filter) => {
  const params = new URLSearchParams(filter);
  history.pushState(filter, '', `?${params}`);
  applyFilter(filter);
};

window.onpopstate = (event) => {
  // state ist null beim Ursprungseintrag
  applyFilter(event.state ?? undefined);
};

setFilter({ kategorie: 'buecher', seite: 1 });
setFilter({ kategorie: 'buecher', seite: 2 });
history.back();

Zeige Kategorie "buecher", Seite 1 Zeige Kategorie "buecher", Seite 2 Zeige Kategorie "buecher", Seite 1

PopStateEvent manuell erzeugen und state prüfen

const event = new PopStateEvent('popstate', {
  state: { modal: 'login' }
});

console.log(event.state.modal);

// Nur lesbar: Zuweisung hat keine Wirkung
event.state = { modal: 'andere' };
console.log(event.state.modal);

// Ohne state-Option ist der Wert null
console.log(new PopStateEvent('popstate').state);

login login null

// Wichtig · Fallstricke

Kein Event bei pushState/replaceState: Das Aufrufen von history.pushState() oder replaceState() löst kein popstate aus. Den Anfangszustand muss man selbst rendern – oder über history.state auslesen.
null einplanen: Beim ersten Eintrag einer Seite und bei Hash-Änderungen ohne gespeicherten Zustand ist state gleich null. Immer mit ?. oder ?? absichern.
Nur klonbare Daten: Der Zustand wird per Structured Clone gespeichert. Funktionen, DOM-Knoten oder Klasseninstanzen (Prototyp geht verloren) lassen sich nicht speichern; bei nicht klonbaren Werten wirft pushState() eine DataCloneError-Ausnahme.
Größenlimit: Browser begrenzen die Größe des serialisierten Zustands (Firefox z. B. etwa 16 MiB). Große Datenmengen gehören besser in sessionStorage oder IndexedDB; im State nur einen Schlüssel ablegen.
Nicht vertrauenswürdig: Der Zustand bleibt über Neuladen hinweg erhalten und kann per Skript gesetzt werden – vor der Verwendung prüfen und nie ungeprüft in innerHTML schreiben.
Kompatibilität: In allen modernen Browsern unterstützt. Ältere Chrome- und Safari-Versionen haben popstate auch beim Laden der Seite ausgelöst (mit state === null). Als moderne Alternative gibt es die Navigation API (navigation.addEventListener('navigate', …)), die aber noch nicht in allen Browsern verfügbar ist.

Siehe auch

History.state CompositionEvent.locale PopStateEvent.hasUAVisualTransition MessageEvent.data InputEvent.data