liveBook · Manning

Navigation API

As explained in Vanilla Web

A browser API for observing and controlling navigation, including intercepting navigations.

A client-side router sometimes needs to change the visible route without replacing the document. The Navigation API provides a central browser interface for observing and intercepting navigations, inspecting session entries, and starting navigations from code. Interception keeps the document alive while the browser updates the URL and history entry; the application then renders the destination view. It does not remove the need for real links or server support for deep links. section 10.3 section 10.3.2 section 10.0

Intercept only navigations the router can handle:

  • Listen for navigate and check event.canIntercept. Leave hash-only changes and downloads to the browser. section 10.3.2
  • Check the destination’s origin and match its route before calling event.intercept(). Unmatched routes retain normal navigation behavior. section 10.3.2
  • Render in the intercept handler. With focusReset and scroll set to "manual", move focus to a meaningful target and call event.scroll() after the new view is in the DOM. section 10.3.2 section 11.1.5
Listing 10.1 Using the Navigation API to intercept same-document navigations
if ("navigation" in globalThis) {
  navigation.addEventListener("navigate", (event) => {
    if (!event.canIntercept || event.hashChange) return; #1
    if (event.downloadRequest) return; #1

    const url = new URL(event.destination.url);
    if (url.origin !== location.origin) return; #1

    // matchRoute is defined in a separate function.
    const match = matchRoute(url.pathname);
    if (!match) return; #2

    event.intercept({
      focusReset: "manual", #3
      scroll: "manual", #3

      async handler() {
        const page = await match.handler(match.params, {
          signal: event.signal #4
        });
        renderPage(page); #5

        document.title = page.title;
        focusMainHeading(); #6

        event.scroll(); #7
      }
    });
  });
}

The interception listing puts eligibility checks, route matching, rendering, cancellation, focus, and scroll timing in one navigate listener. section 10.3.2

Pass event.signal to route loaders and fetch calls. It aborts when another navigation supersedes the current one; treat the resulting AbortError as cancellation rather than a route failure. For other failures, render an error state. To observe completion outside the handler, use navigatesuccess, navigateerror, or the in-progress navigation.transition.finished promise: event.intercept() itself does not return a promise. section 10.3.3 section 10.3.5

The navigate event also covers form submissions. GET form fields appear in the destination URL; POST data is available through event.formData when handling an eligible navigation. This avoids treating every form as a click, though a History API fallback needs separate submit handling if it must intercept forms. section 10.3.4

Navigate after saving

After a successful save, call navigation.navigate("/settings/saved", { history: "replace" }). The existing navigate listener can intercept and render it through the same path as a link click. Await the returned finished promise when the caller needs rendering to complete; committed only indicates that the URL and entry changed. section 11.2

History entries belong to the current tab and expose only entries the page is allowed to see, primarily same-origin entries—not the user’s complete browser history. The API is Baseline 2026, not a universal assumption for older browsers or web views. Feature-detect it and retain a History API fallback with manual internal-link interception and popstate handling. Keep links as <a href> so ordinary browser navigation still works without the enhancement. section 10.3.1 section 10.3.2 section 10.3.5 section 10.5

How Vanilla Web covers it

How deep it goes
Works through interception guards, rendering, cancellation, focus, scroll, forms, completion, and programmatic navigation, with a History API fallback.
Examples
Uses an interception listener, abortable product fetch, form handler, and navigation after a successful save.
What it assumes
Assumes familiarity with URLs, links, JavaScript event listeners, and route handlers; introduces navigation interception from browser primitives.
What you can do after
Build it from scratch as a progressively enhanced router that intercepts eligible routes and shares one rendering path with programmatic navigation.
How it connects
Connects route matching, session history, AbortSignal, form submissions, scroll restoration, and the History API.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.