0Pricing
HTML Academy · Lesson

The Navigation API modern browsers

Use the Navigation API to intercept and customize navigations.

The Navigation API modern browsers is a free HTML Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the HTML Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

A Modern Replacement

The Navigation API is a newer, more powerful replacement for the History API. It treats navigations as first-class objects you can intercept, abort, and await — closer to how SPAs actually need to handle routing in 2024.

window.navigation Object

window.navigation exposes the entry list, the current entry, and the navigate event. navigation.entries() returns every entry in the current history; navigation.currentEntry is the active one. Compare to History API's opaque length and unread state.

The navigate Event

Listen to navigation.addEventListener("navigate", handler) to intercept every same-document navigation — link clicks, form submissions, back/forward, programmatic. A single hook replaces the patchwork of click interception + popstate + form submit listeners.

navigation.addEventListener("navigate", (e) => {
  if (!e.canIntercept) return;
  e.intercept({
    handler: async () => {
      await renderPage(new URL(e.destination.url).pathname);
    }
  });
});

intercept and handler

Calling e.intercept({ handler }) claims the navigation. The handler returns a promise; while it pending, the navigation is "in progress" and the URL is already updated. This unifies the historical race between URL change and view render.

canIntercept Check

Not all navigations can be intercepted (cross-origin, downloads). Check e.canIntercept before calling intercept. The defensive guard is a one-liner that distinguishes SPA navigation from real cross-origin departures.

navigation.navigate Method

navigation.navigate(url, options) programmatically triggers a navigation, equivalent to a click. The returned object has committed and finished promises so you can await the URL change or full handler completion.

Entry State and Keys

Each navigation entry has a stable key (across reloads) and an id (per session). Use the key for persistent state (saved scroll positions, form drafts) and id for transient state. The History API's only state was an opaque blob.

Back and Forward

navigation.back() and navigation.forward() are convenience wrappers around traverseTo. They return the same { committed, finished } promise pair, so you can await the back navigation before doing follow-up work.

Aborting Navigations

If the user clicks a second link while the first is still rendering, the in-progress navigation can be aborted. The handler receives an AbortSignal via e.signal; pass it to fetch calls so stale work is cancelled when the new navigation begins.

e.intercept({
  handler: async () => {
    const data = await fetch(url, { signal: e.signal });
    renderPage(await data.json());
  }
});

Why Not Just Use History?

The History API works but is awkward: state changes and view rendering are decoupled, click handling is manual, multi-listener coordination is fragile, scroll restoration is incomplete. The Navigation API was designed for SPA needs from the start and addresses each of these.

Browser Support

Chrome and Edge support the Navigation API. Safari and Firefox lag (as of early 2026); ship code that feature-detects ("navigation" in window) and falls back to History + popstate when unavailable. Frameworks like SvelteKit and TanStack Router already wrap this detection.

When to Adopt

For new projects targeting Chromium-first audiences, adopt now and accept the History fallback. For broad-audience public sites, wait for Safari/Firefox support (or use a router library that abstracts both). The simpler API is worth the wait.

Knowledge Check

What is the main advantage of the Navigation API's navigate event over the History API's combination of popstate plus manual click interception?

Summary

The Navigation API unifies SPA navigation under a single navigate event with intercept/abort semantics, stable per-entry keys, and async handler awaiting. It replaces the History+popstate+click-interception patchwork. Supported in Chromium browsers today; feature-detect and fall back to History for cross-browser code until Safari and Firefox catch up.

Frequently asked questions

Is the “The Navigation API modern browsers” lesson free?

Yes — the full text of “The Navigation API modern browsers” is free to read here on the web, and the HTML Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the HTML Academy course, upgrade to CoddyKit PRO.

What will I learn in “The Navigation API modern browsers”?

Use the Navigation API to intercept and customize navigations. You practise HTML Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start HTML Academy?

No prior experience is required. HTML Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “The Navigation API modern browsers” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this HTML Academy lesson?

Yes. Every HTML Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. pushState and replaceState
  2. The popstate Event
  3. Hash-Based vs Path-Based Routing
  4. The Navigation API modern browsers
← Back to HTML Academy