Navigation.navigate() — Methode · JavaScript-Referenz

Signatur

Navigation.prototype.navigate(url, options)

Beschreibung

Die Methode navigate() der Navigation-Schnittstelle (erreichbar über window.navigation) startet eine Navigation zur angegebenen URL. Sie ist das moderne Gegenstück zu location.assign(), location.replace() sowie history.pushState()/replaceState() und fasst deren Aufgaben in einer einzigen, promise-basierten API zusammen.

Jeder Aufruf löst ein navigate-Ereignis auf dem Navigation-Objekt aus. In Single-Page-Applications fängt man dieses Ereignis mit event.intercept() ab und rendert den neuen Inhalt selbst, ohne dass die Seite neu geladen wird. Wird die Navigation nicht abgefangen, lädt der Browser das Dokument ganz normal.

Über die Optionen lässt sich ein persistenter Zustand (state) an den neuen Verlaufseintrag hängen, der sich später mit navigation.currentEntry.getState() auslesen lässt. Mit info übergibt man flüchtige Daten nur an den navigate-Handler, z. B. die gewünschte Animationsrichtung. Mit history legt man fest, ob ein neuer Eintrag angelegt ("push") oder der aktuelle ersetzt wird ("replace").

Der Rückgabewert enthält zwei Promises: committed wird erfüllt, sobald sich die sichtbare URL geändert hat und der neue Eintrag feststeht. finished wird erfüllt, wenn alle von intercept() gelieferten Handler-Promises abgeschlossen sind. Beide werden zurückgewiesen, wenn die Navigation abgebrochen wird oder fehlschlägt.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string		Ziel-URL, absolut oder relativ zur aktuellen Dokument-URL.
$options	object	{}	Optionales Objekt mit den folgenden Eigenschaften.
$options.state	any	undefined	Entwickler-definierter Zustand, der im neuen `NavigationHistoryEntry` gespeichert wird. Er muss strukturiert klonbar sein und lässt sich über `getState()` auslesen.
$options.info	any	undefined	Flüchtige Daten, die nur im `navigate`-Ereignis als `event.info` ankommen und nicht gespeichert werden.
$options.history	"auto" \| "push" \| "replace"	"auto"	`"push"` legt einen neuen Verlaufseintrag an, `"replace"` ersetzt den aktuellen. Bei `"auto"` wird normalerweise `push` verwendet, bei gleicher URL oder beim ersten Laden jedoch `replace`.

Rückgabewert

Typ

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

Beschreibung

Ein Objekt mit zwei Promises, die jeweils mit dem neuen NavigationHistoryEntry erfüllt werden: committed, sobald sich die URL geändert hat, und finished, sobald alle Intercept-Handler abgeschlossen sind.

Beispiele

SPA-Routing mit navigate() und intercept()

// Zentraler Router: fängt alle Navigationen innerhalb der eigenen Origin ab
navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept || event.hashChange || event.downloadRequest) return;

  const url = new URL(event.destination.url);
  event.intercept({
    async handler() {
      const res = await fetch(`/partials${url.pathname}.html`);
      document.querySelector('main').innerHTML = await res.text();
    }
  });
});

// Programmatisch navigieren
const { committed, finished } = navigation.navigate('/produkte');
await committed;
console.log('URL geändert:', location.pathname);
await finished;
console.log('Inhalt geladen');

URL geändert: /produkte Inhalt geladen

Zustand speichern und später auslesen

await navigation.navigate('/suche?q=js', {
  state: { filter: 'neueste', seite: 2 }
}).finished;

const state = navigation.currentEntry.getState();
console.log(state.filter, state.seite);

neueste 2

Aktuellen Eintrag ersetzen und info übergeben

navigation.addEventListener('navigate', (event) => {
  console.log('Animation:', event.info?.animation ?? 'keine');
});

// Kein neuer Verlaufseintrag – z. B. nach dem Login-Redirect
navigation.navigate('/dashboard', {
  history: 'replace',
  info: { animation: 'fade' }
});

Animation: fade

Fehler und Abbruch behandeln

try {
  await navigation.navigate('/profil').finished;
} catch (err) {
  // AbortError, wenn eine neue Navigation die alte unterbricht
  console.warn('Navigation fehlgeschlagen:', err.name);
}

Navigation fehlgeschlagen: AbortError

// Wichtig · Fallstricke

Browser-Unterstützung: In Chromium-Browsern (Chrome, Edge, Opera) ab Version 102 verfügbar. Firefox unterstützt die Navigation API ab Version 147, Safari ab 26.2. Für ältere Browser sollte man per Feature-Erkennung (if ('navigation' in window)) auf die History-API zurückfallen.
Fehlerfälle: Wird history: "push" angegeben, obwohl ein Push nicht möglich ist (etwa während das erste Dokument noch lädt oder bei einer javascript:-URL), wirft die Methode synchron einen NotSupportedError. Ungültige URLs führen zu einem SyntaxError, ein nicht klonbarer state zu einem DataCloneError. In diesen Fällen werden die Promises zurückgewiesen.
Abbruch: Startet vor dem Abschluss eine neue Navigation, wird die laufende abgebrochen und finished mit einem AbortError zurückgewiesen. Unbehandelte Zurückweisungen erscheinen als Konsolenfehler. Deshalb sollte man finished immer mit await in try/catch oder mit .catch() behandeln.
state und info nicht verwechseln: Nur state bleibt am Verlaufseintrag erhalten, auch bei Vor- und Zurück-Navigation. info gilt nur für diese eine Navigation.
Ohne intercept() im navigate-Handler lädt der Browser die Seite vollständig neu. Ursprungsübergreifende (cross-origin) Navigationen lassen sich nicht abfangen (event.canIntercept === false).
Sicherheit: Werden per Fetch geladene Inhalte über innerHTML eingefügt, sollten sie aus vertrauenswürdigen Quellen stammen oder bereinigt werden, um XSS zu verhindern.

Siehe auch

Navigation NavigateEvent.intercept() Navigation.reload() Navigation.traverseTo() Navigation.back() NavigationHistoryEntry.getState() History.pushState()