Navigation API: Moderne SPA-Navigation ohne History API

1. Warum die History API fuer Routing nie die richtige Wahl war

Die History API mit pushState(), replaceState() und dem popstate-Event wurde 2010 eingefuehrt, um Ajax-Anwendungen zu erlauben, die Adressleiste zu aendern, ohne einen vollen Seitenwechsel auszuloesen. Sie war jedoch nie als Navigations-Framework gedacht, sondern als reine Historien-Manipulation, weshalb SPA-Router seit anderthalb Jahrzehnten Krücken bauen muessen: Klicks auf Links werden per addEventListener('click', ...) abgefangen, event.preventDefault() verhindert den Standard-Seitenwechsel, und pushState() simuliert danach die URL-Aenderung.

Das Problem dabei ist, dass diese Konstruktion nichts ueber die eigentliche Navigations-Absicht weiss. Es gibt keinen eingebauten Weg zu erkennen, ob eine Navigation gerade lief, ob sie abgebrochen wurde, oder welche Art von Navigation es war, ein Klick, ein Zurueck-Button, ein Formular-Absenden. Das popstate-Event feuert zudem nicht bei pushState() selbst, sondern nur bei Vor-/Zurueck-Navigation, was zu inkonsistenter Router-Logik zwingt.

2. Das Grundkonzept: ein zentrales navigate-Event fuer alles

Die Navigation API, verfuegbar unter window.navigation, fasst alle Arten von Navigation, Link-Klicks, Formular-Absenden, Vor-/Zurueck-Buttons und programmatische Aufrufe in einem einzigen navigate-Event zusammen. Jede Navigation, ob vom Nutzer oder vom Code ausgeloest, durchlaeuft diesen einen Punkt, an dem ein Router zentral entscheiden kann, wie damit umzugehen ist.

Damit entfaellt die fragile Klick-Abfang-Logik komplett. Statt jeden Link individuell zu ueberwachen, registriert ein Router einmal einen navigate-Listener auf dem globalen navigation-Objekt und erhaelt darueber Informationen wie destination.url, navigationType (push, replace, reload, traverse) und ob die Navigation vom selben Dokument ausgeht.

// Grundstruktur eines Navigation-API-Listeners
navigation.addEventListener('navigate', (event) => {
  const url = new URL(event.destination.url);

  console.log('Navigationstyp:', event.navigationType); // push | replace | reload | traverse
  console.log('Ziel:', url.pathname);
  console.log('Vom Nutzer initiiert:', event.userInitiated);
});

3. Navigation abfangen mit intercept()

Der eigentliche Kern fuer SPA-Router ist event.intercept(). Damit teilt der Router dem Browser mit: 'Ich uebernehme diese Navigation selbst, lade keine neue Seite'. Innerhalb der intercept()-Optionen wird ein handler als async-Funktion uebergeben, die das eigentliche Rendering des neuen View-Zustands uebernimmt, etwa das Laden von Daten und das Austauschen des DOM-Inhalts.

Der entscheidende Vorteil gegenueber dem alten Ansatz ist, dass der Browser waehrend der intercept()-Handler-Ausfuehrung automatisch einen Ladezustand signalisiert, etwa den Stop-Button in der Adressleiste aktiviert, und dass Scroll-Position-Restoration korrekt gehandhabt wird, ohne dass der Router das selbst nachbauen muss. Faellt der handler mit einer Exception aus, bleibt die Navigation sauber im vorherigen Zustand.

// Minimaler SPA-Router mit Navigation API
navigation.addEventListener('navigate', (event) => {
  // Externe Links, Downloads etc. nicht abfangen
  if (!event.canIntercept || event.hashChange || event.downloadRequest) {
    return;
  }

  const url = new URL(event.destination.url);

  event.intercept({
    async handler() {
      const view = await resolveRoute(url.pathname);
      document.getElementById('app').replaceChildren(view);
    },
  });
});

4. Programmatisches Navigieren mit navigation.navigate()

Fuer programmatische Navigation, etwa nach einem erfolgreichen Formular-Absenden, ersetzt navigation.navigate(url, options) die Kombination aus history.pushState() plus manuellem View-Update. Die Methode gibt ein Objekt mit zwei Promises zurueck, committed und finished: committed loest auf, sobald die URL-Aenderung sichtbar ist, finished erst, wenn der intercept()-Handler vollstaendig durchgelaufen ist.

Dieses zweistufige Promise-Modell ist ein echter Fortschritt gegenueber pushState(), das synchron und ohne jede Rueckmeldung ueber den Erfolg der eigentlichen View-Aktualisierung arbeitet. Ein Router kann jetzt beispielsweise ein Ladeindikator anzeigen, bis finished aufgeloest ist, und bei einem Fehler in finished gezielt reagieren, ohne eigene Event-Bus-Konstruktionen bauen zu muessen.

// Programmatische Navigation nach Formular-Absenden
async function handleFormSubmit(orderId) {
  const { committed, finished } = navigation.navigate(`/orders/${orderId}`, {
    state: { fromCheckout: true },
  });

  await committed;   // URL ist jetzt aktualisiert
  showSkeletonLoader();

  await finished;    // View ist vollstaendig gerendert
  hideSkeletonLoader();
}

5. Zugriff auf den kompletten Navigations-Verlauf

Waehrend die History API praktisch keinen Einblick in die eigene Historie erlaubt, außer der Laenge ueber history.length, stellt navigation.entries() eine vollstaendige, iterierbare Liste aller NavigationHistoryEntry-Objekte der aktuellen Session bereit. Jeder Eintrag hat eine stabile key- und id-Eigenschaft, url, sowie ueber getState() den bei der Navigation mitgegebenen State.

Das erlaubt Router-Muster, die vorher praktisch unmoeglich waren, etwa das Erkennen, ob eine Zurueck-Navigation innerhalb der eigenen App stattfindet oder von einer externen Seite kommt, indem currentEntry.index mit dem Index des vorherigen Eintrags verglichen wird. Auch Scroll-Restoration pro Route laesst sich darueber deutlich praeziser steuern als mit den bisherigen Heuristiken des Browsers.

// Kompletten Navigationsverlauf inspizieren
for (const entry of navigation.entries()) {
  console.log(entry.index, entry.url, entry.getState());
}

console.log('Aktueller Eintrag:', navigation.currentEntry.url);
console.log('Kann zurueck:', navigation.canGoBack);
console.log('Kann vor:', navigation.canGoForward);

6. Navigation gezielt verhindern oder umleiten

Ein haeufiger Anwendungsfall ist das Verhindern einer Navigation, etwa wenn ein Formular ungespeicherte Aenderungen enthaelt. Mit der klassischen History API musste dafuer der umstaendliche beforeunload-Dialog missbraucht werden, der nur bei echtem Seitenverlassen greift, nicht bei SPA-interner Navigation. Die Navigation API loest das direkt im navigate-Event ueber event.preventDefault().

Innerhalb des Handlers kann der Router pruefen, ob ungespeicherte Aenderungen vorliegen, und bei Bedarf einen eigenen Bestaetigungsdialog anzeigen, bevor die Navigation tatsaechlich stattfindet oder verworfen wird. Das gibt Entwicklern volle Kontrolle ueber den Ablauf, ohne auf Browser-native, kaum anpassbare Dialoge angewiesen zu sein.

// Navigation bei ungespeicherten Aenderungen abfangen
let hasUnsavedChanges = false;

navigation.addEventListener('navigate', (event) => {
  if (!hasUnsavedChanges || !event.canIntercept) return;

  event.intercept({
    async handler() {
      const confirmed = await showCustomConfirmDialog(
        'Ungespeicherte Aenderungen verwerfen?'
      );
      if (!confirmed) {
        throw new Error('Navigation vom Nutzer abgebrochen');
      }
      hasUnsavedChanges = false;
      await renderRoute(new URL(event.destination.url));
    },
  });
});

7. Direkter Vergleich: History API vs. Navigation API

Der zentrale konzeptionelle Unterschied ist, dass die History API historienzentriert ist, sie manipuliert einen Stack von Eintraegen, waehrend die Navigation API navigationszentriert ist, sie modelliert den Vorgang der Navigation selbst als Ereignis mit Lebenszyklus. Diese Verschiebung macht Router-Code deutlich deklarativer: Statt Klicks abzufangen und Zustaende manuell zu synchronisieren, reagiert der Code auf ein einziges, gut definiertes Ereignis.

In der Praxis bedeutet das weniger Boilerplate, weniger Edge-Case-Bugs bei Vor-/Zurueck-Navigation und eingebaute Ladezustaende. Der Nachteil ist die Browser-Unterstuetzung: Die Navigation API ist bislang nur in Chromium-basierten Browsern verfuegbar, sodass produktive Router weiterhin einen History-API-Fallback fuer Firefox und Safari benoetigen, meist ueber ein Feature-Detection-Pattern mit 'navigation' in window.

Ein weiterer, oft uebersehener Unterschied betrifft Formular-Navigation. Mit der History API muss ein Router Formular-Submits separat abfangen, meist ueber einen eigenen submit-Listener, der ebenfalls preventDefault() aufruft und die Formulardaten manuell in eine URL oder einen Request umwandelt. Die Navigation API behandelt Formular-Submits hingegen als ganz normale Navigation im selben navigate-Event, inklusive formData auf dem Event-Objekt, sodass ein Router keine zweite, parallele Abfang-Logik mehr pflegen muss.

8. Migrationsstrategie fuer bestehende Router

Ein bestehender pushState()-basierter Router muss nicht komplett neu geschrieben werden, um von der Navigation API zu profitieren. Sinnvoll ist eine Abstraktionsschicht, die intern pruft, ob 'navigation' in window verfuegbar ist, und je nach Ergebnis entweder den navigate-Event-Listener mit intercept() oder die klassische Klick-Abfang-Logik mit pushState() nutzt, waehrend die oeffentliche Router-API fuer den Rest der Anwendung unveraendert bleibt.

Fuer neue Projekte, die bewusst nur moderne Chromium-Browser als Zielgruppe fuer erweiterte Features akzeptieren, etwa interne Tools oder PWA-Kontexte mit bekannter Nutzerbasis, kann die Navigation API bereits heute die alleinige Grundlage sein, mit einem simplen Redirect-Hinweis fuer nicht unterstuetzende Browser.

Sinnvoll ist zudem ein schrittweises Vorgehen: Zunaechst wird nur das Lesen des Navigations-Verlaufs ueber navigation.entries() ergaenzt, etwa fuer praezisere Scroll-Restoration, ohne die bestehende Klick-Abfang-Logik anzutasten. Erst in einem zweiten Schritt wird intercept() als Ersatz fuer die manuelle preventDefault()-Logik eingefuehrt. So laesst sich die Migration in kleinen, risikoarmen Schritten testen, statt den kompletten Router auf einmal umzustellen.

9. Fazit: ein echtes Navigations-Primitive statt Workarounds

Die Navigation API ist keine kleine Erweiterung der History API, sondern eine grundsaetzlich andere, deutlich passendere Abstraktion fuer SPA-Routing. Mit intercept(), dem zweistufigen navigate()-Promise-Modell und dem vollstaendigen entries()-Zugriff loest sie Probleme, fuer die SPA-Router bislang eigene, fehleranfaellige Workarounds bauen mussten.

Solange die Browser-Unterstuetzung nicht vollstaendig ist, bleibt ein Fallback noetig, doch fuer Projekte mit Chromium-Fokus oder progressiver Verbesserung lohnt sich der Umstieg schon jetzt. Die folgende Tabelle stellt beide Ansaetze direkt gegenueber.

10. Zusammenfassung

11. FAQ: Navigation API: Das Wichtigste auf einen Blick