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
