Navigation API: modern routing for web applications
Understand the 2026 Navigation API, centralized navigation events, history entries, focus and scroll handling, fallbacks and safe SPA adoption.
What became available in 2026
The Navigation API became Baseline Newly available across current major browser engines in January 2026. It is designed as a modern successor to the combination of window.location, the History API, popstate listeners and document-wide link interception commonly used by single-page application routers. The global navigation object provides one place to observe, initiate and track navigation within a browsing context.
Newly available does not mean every visitor has already upgraded. Older browsers and embedded webviews can remain in use for years. A site should preserve real links, server routes and ordinary form behavior so core navigation still works without interception. The API can then enhance same-origin movement where capability detection and the product's browser policy allow it.
Handle navigation from one event
The navigate event can represent link activation, form submission, reload, back or forward traversal and programmatic navigation. Its destination, navigation type, form data and canIntercept value help a router decide whether it should intervene. A handler must leave downloads, cross-origin destinations, unsupported schemes and other non-interceptable cases to the browser rather than forcing every event through application rendering.
Calling event.intercept() turns an eligible navigation into application-controlled work. The handler can fetch data, render the destination and reject if the transition fails. The API emits success or error events and exposes committed and finished promises. Await the right phase: committed means the URL and history entry changed, while finished means the asynchronous handler completed. Avoid starting overlapping transitions without a clear cancellation policy.
Work with entries and state deliberately
navigation.entries() exposes same-origin entries created in the current browsing context, and currentEntry identifies the active one. Methods such as navigate, reload, back, forward and traverseTo operate on this model. Entry keys are useful for returning to a known point without guessing how many steps exist between the current screen and the destination.
History state should remain small, serializable and free of secrets. Store enough information to restore a view, such as filters or a selected tab, while keeping authoritative records in application storage or the server. updateCurrentEntry can change state without adding another URL. Test disposal of forward entries after a user goes back and then follows a different path, because stale assumptions can produce broken restoration logic.
Preserve focus, scroll and accessibility
A successful router does more than replace HTML. After navigation, move focus to a useful landmark or heading when appropriate, announce important changes through the document structure and preserve the browser's back-button expectations. Native links should remain links so keyboard commands, context menus, new tabs, copied addresses and assistive technology retain familiar behavior.
The API can coordinate scroll restoration with asynchronous rendering. If a back navigation returns to a long list, load enough content before asking the event to restore its saved position. For a new destination, the expected result may be the top or a fragment target. Test slow responses, aborted fetches and rapid back-forward actions. Pair animated view transitions with reduced-motion support and never delay navigation only for decoration.
Keep server routes and failure paths real
Every public URL should return useful content when opened directly or refreshed. Client interception cannot repair a host that sends 404 for an application route, and a loading failure should not leave the address bar showing content that never appeared. Render an error associated with the destination, offer retry or allow a normal document navigation when recovery is safer.
Security rules still apply during client navigation. Confirm same-origin destinations before interception, encode URL values correctly, enforce authorization on the server and avoid inserting fetched markup through unsafe sinks. A router must not treat an earlier client-side permission check as proof that a later API request is allowed. Keep analytics from recording sensitive state embedded in URLs or navigation metadata.
Worked example: progressively enhance a tool directory
Begin with a server-rendered directory where every tool card is an ordinary anchor and every destination is independently available. When window.navigation exists, listen for eligible same-origin navigations. Ignore modifier-clicks, downloads and links outside the application. Intercept the remaining navigation, fetch or select the route content, update the main region and document title, then place focus on the destination heading.
Test direct entry, refresh, back, forward, fragment links, failed loading and two fast clicks. In an older browser, the same anchors perform full-page navigation and remain completely usable. This layered approach gains centralized events and smoother transitions without making a new API responsible for basic access to the tools.
Quick checklist
- Keep real links, forms and server routes.
- Feature-detect window.navigation before enhancement.
- Intercept only eligible same-origin navigations.
- Handle committed, finished, failure and cancellation states.
- Test keyboard focus, scroll restoration and reduced motion.
- Protect authorization and URL data on the server.
Primary references
Standards and platform support change. Use these authoritative sources to check the current specification and migration guidance.