Navigation.back() — Methode · JavaScript-Referenz

Signatur

Navigation.prototype.back(options)

Beschreibung

Die Methode back() der Navigation-Schnittstelle (erreichbar über window.navigation) springt einen Eintrag in der Navigationshistorie zurück. Sie ist das moderne Gegenstück zu history.back(). Der Unterschied: Sie gibt Promises zurück, mit denen man sauber auf den Abschluss der Navigation warten kann.

Der Rückgabewert ist ein Objekt mit zwei Promises. committed wird erfüllt, sobald sich die sichtbare URL geändert hat und der neue NavigationHistoryEntry aktiv ist. finished wird erfüllt, sobald alle Promises abgeschlossen sind, die im navigate-Event an intercept() übergeben wurden. Schlägt die Navigation fehl oder wird sie abgebrochen, werden beide Promises abgelehnt.

Vor dem Aufruf sollte man navigation.canGoBack prüfen. Gibt es keinen vorherigen Eintrag, werden die Promises mit einer DOMException vom Typ InvalidStateError abgelehnt. Über options.info kann man beliebige Daten an den navigate-Handler durchreichen, zum Beispiel um eine Rückwärts-Animation auszulösen.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Einstellungsobjekt.
$options.info	any	undefined	Beliebige Daten, die im ausgelösten `navigate`-Event als `event.info` ankommen. Sie werden nicht im Historien-Eintrag gespeichert.

Rückgabewert

Typ

{ committed: Promise<NavigationHistoryEntry>, finished: Promise<NavigationHistoryEntry> }

Beschreibung

Ein Objekt mit zwei Promises. committed wird erfüllt, wenn der Ziel-Eintrag aktiv geworden ist. finished wird erfüllt, wenn auch alle abgefangenen Handler fertig sind. Beide liefern den neuen NavigationHistoryEntry.

Beispiele

Zurück-Button mit Prüfung über canGoBack

const backBtn = document.querySelector('#back');

// Button nur aktivieren, wenn es einen vorherigen Eintrag gibt
const updateButton = () => {
  backBtn.disabled = !navigation.canGoBack;
};

navigation.addEventListener('currententrychange', updateButton);
updateButton();

backBtn.addEventListener('click', async () => {
  if (!navigation.canGoBack) return;
  try {
    const entry = await navigation.back().finished;
    console.log('Zurück auf:', entry.url);
  } catch (err) {
    console.error('Navigation fehlgeschlagen:', err.name);
  }
});

Zurück auf: https://example.com/produkte

info an den navigate-Handler übergeben (SPA-Animation)

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  const direction = event.info?.direction ?? 'forward';

  event.intercept({
    async handler() {
      document.body.dataset.transition = direction;
      const url = new URL(event.destination.url);
      document.querySelector('main').textContent = `Seite: ${url.pathname}`;
    }
  });
});

// Rückwärts navigieren und die Richtung mitschicken
const { committed, finished } = navigation.back({ info: { direction: 'back' } });
await committed;
console.log('URL geändert:', location.pathname);
await finished;
console.log('Handler abgeschlossen');

URL geändert: /start Handler abgeschlossen

Fallback auf history.back() bei fehlender Unterstützung

const goBack = async () => {
  if ('navigation' in window) {
    if (!navigation.canGoBack) {
      console.log('Kein vorheriger Eintrag vorhanden');
      return;
    }
    await navigation.back().committed;
  } else {
    history.back(); // kein Promise, kein Fehler-Feedback
  }
};

document.querySelector('#back').addEventListener('click', goBack);

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome und Edge unterstützen die Navigation API seit Version 102, Firefox seit 147 und Safari seit 26.2. Ältere Browser brauchen eine Feature-Erkennung mit 'navigation' in window und history.back() als Fallback.
Ohne vorherigen Eintrag wirft back() keinen synchronen Fehler. Stattdessen werden beide Promises mit einem InvalidStateError abgelehnt. Wenn man diese Ablehnung nicht behandelt, erscheint ein „Unhandled Promise Rejection“. Deshalb vorher navigation.canGoBack prüfen.
Die Navigation API bildet nur Einträge derselben Herkunft (Origin) im aktuellen Frame ab. Liegt der vorherige Eintrag auf einer anderen Origin, ist canGoBack false, auch wenn history.back() noch funktionieren würde.
Wird die Navigation durch eine neuere Navigation, durch event.preventDefault() oder durch einen Fehler im intercept()-Handler abgebrochen, wird finished mit einem AbortError abgelehnt.
Ein Zurückspringen über Dokumentgrenzen hinweg lädt die Seite neu. In diesem Fall wird finished im alten Dokument nie erfüllt.
info ist flüchtig: Es wird nur im navigate-Event übergeben und nicht wie state im Eintrag gespeichert.

Siehe auch

Navigation Navigation.forward() Navigation.navigate() History.back() Navigation.reload()