The Navigation API: Modern Client-Side Routing for SPAs
The Navigation API: Modern Client-Side Routing for SPAs
Background and Motivation
Single-Page Applications (SPAs) have relied on the History API for over a decade to simulate multi-page navigation without full page reloads. However, the History API was never designed for the demands of modern SPAs. Developers had to assemble a fragile puzzle:
- Listen globally for
<a>clicks, callpreventDefault(), manually invokehistory.pushState(), and then update the DOM. - Separately listen for
popstateto handle browser back/forward buttons. - Miss certain navigation types (e.g., programmatic
location.hrefchanges, some form submissions). - Inability to read the full history stack or edit non-current entries.
- Inconsistent
popstatebehavior—does not fire onpushState/replaceState.
This led to brittle routers with edge cases where users end up on the wrong view or lose scroll position.
The Navigation API addresses these architectural gaps. It provides a centralized navigate event that captures all navigation triggers—link clicks, back/forward, form submissions, and programmatic calls—along with powerful primitives like intercept(), commit/finished promises, manual scroll control, and state management. As of early 2026, with Safari and Firefox joining Chrome, the Navigation API is Baseline Newly available across all major browsers.
Prerequisites
Before adopting the Navigation API, verify support and prepare a fallback strategy.
Browser Support Matrix
- Chrome / Edge: 102+
- Samsung Internet: 19.0+
- Safari: 26.2+ (2025+)
- Firefox: 147+ (2026+)
- iOS Safari: 26.2+
Older browsers lack the API entirely. Always include feature detection and a legacy path.
Feature Detection
const hasNavigationAPI = 'navigation' in window && typeof window.navigation === 'object';If unsupported, fall back to History API-based routing or a minimal SPA shim.
if (!hasNavigationAPI) {
// Legacy History API fallback
window.addEventListener('popstate', handlePopState);
document.querySelectorAll('a[href]').forEach(link => {
link.addEventListener('click', (e) => {
if (isSameOrigin(link.href)) {
e.preventDefault();
const url = new URL(link.href);
window.history.pushState({ path: url.pathname }, '', url.pathname);
renderApp(url.pathname);
}
});
});
}Build Tool Configuration
No special bundler setup is required. However, if using TypeScript, ensure lib in tsconfig.json includes "DOM" and ideally a recent version with Navigation API types.
Step 1: Preparation
The first step is centralizing navigation logic with a single listener.
Basic Setup
In your main entry file (e.g., src/router.ts):
if (hasNavigationAPI) {
window.navigation.addEventListener('navigate', (event) => {
// Handle all navigations here
});
}Intercept Eligibility
Not all navigations can or should be intercepted. Check event.canIntercept:
- Cross-origin navigations:
canInterceptisfalse. The browser handles them with a full reload. - Same-origin, same-document: interceptable.
Also skip event.hashChange (fragment scrolls) and event.downloadRequest (file downloads).
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
if (event.hashChange || event.downloadRequest !== null) {
return; // Let the browser handle these natively
}
const url = new URL(event.destination.url);
// Proceed to intercept
});Key insight: By handling all eligible navigations in one place, you eliminate the need for multiple event listeners and edge-case glue code.
Step 2: Core Implementation
Now we implement the heart of the router: intercept handlers with async content loading, proper scroll management, and state persistence.
Intercept with Async Handler
The intercept() method accepts an object with a handler callback. This callback may be async. The Navigation API waits for the returned promise before firing navigatesuccess.
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
if (event.hashChange || event.downloadRequest !== null) return;
const url = new URL(event.destination.url);
event.intercept({
async handler() {
// Show loading state immediately (optional)
renderPlaceholder();
// Fetch new content (from network or cache)
const content = await fetchPageContent(url.pathname);
// Update DOM
document.getElementById('app').innerHTML = content;
}
});
});Two-phase commit (advanced): The spec defines precommitHandler for redirects before the URL updates. Use it if your app needs to rewrite URLs during login flows or A/B tests:
event.intercept({
precommitHandler: (controller) => {
if (needsAuth) {
return controller.redirect('/signin');
}
},
async handler() {
// Normal render
}
});Manual Scroll Control
By default, the browser attempts scroll restoration as soon as intercept() is called. For SPAs that render content asynchronously, this often results in scrolling before the page has height.
Set scroll: 'manual' and call event.scroll() after content is ready:
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
event.intercept({
scroll: 'manual',
async handler() {
const data = await fetchListData();
renderList(data);
// Now the document has the correct height; restore scroll position
event.scroll();
}
});
});This pattern is critical for back/forward navigation where users expect to return to their prior scroll offset.
State Management
The Navigation API stores arbitrary state on each history entry. This is superior to the History API where state could only be set during pushState.
To set state during navigation:
navigation.navigate('/dashboard', { state: { visitCount: 5, filters: { status: 'open' } } });To retrieve state:
const entry = navigation.currentEntry;
const state = entry.getState(); // { visitCount: 5, filters: { status: 'open' } }
For non-navigation state changes (e.g., expanding a <details> element), use updateCurrentEntry():
details.addEventListener('toggle', () => {
const expanded = details.open;
navigation.updateCurrentEntry({
state: { ...navigation.currentEntry.getState(), detailsExpanded: expanded }
});
});This ensures browser back/forward restores UI state without reloading.
Integration with View Transitions
The Navigation API and View Transitions API are designed to work together. Wrap DOM updates in document.startViewTransition():
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
const url = new URL(event.destination.url);
event.intercept({
async handler() {
const content = await fetchPageContent(url.pathname);
document.startViewTransition(() => {
document.getElementById('app').innerHTML = content;
});
}
});
});The browser snapshots the old UI, executes your callback, and animates to the new state—yielding an app-like transition without custom animations.
Form Submission Handling
The navigate event exposes event.formData for same-origin POST submissions. Intercept to avoid page reloads:
navigation.addEventListener('navigate', (event) => {
if (event.formData && event.canIntercept) {
event.intercept({
async handler() {
const data = event.formData;
const username = data.get('username');
await api.login(username, data.get('password'));
renderSuccess(`Welcome, ${username}!`);
}
});
}
});Standard HTML forms just work—no onsubmit handlers needed.
Navigation Lifecycle Events
Track navigation completion and errors:
navigation.onnavigatesuccess: fires afterhandler()resolves.navigation.onnavigateerror: fires ifhandler()rejects.navigation.transition.finished: promise for the current navigation’s completion.
navigation.addEventListener('navigatesuccess', () => {
console.log('Navigation committed successfully');
});
navigation.addEventListener('navigateerror', (event) => {
console.error('Navigation failed:', event.error);
// Show fallback UI or retry
});Traversing History
Use typed methods for precise control:
navigation.back(),navigation.forward(): standard traversal.navigation.traverseTo(key): jump to a specific entry by itsNavigationHistoryEntry.key.navigation.reload(): reload current entry.
// Remember the first page the user landed on
const homeKey = navigation.currentEntry.key;
// Always return to the root of the session
document.getElementById('home-btn').onclick = () => {
navigation.traverseTo(homeKey);
};Step 3: Verification and Tuning
Feature Detection Checklist
In CI or automated tests, assert:
test('has Navigation API support', () => {
expect('navigation' in window).toBe(true);
expect(typeof window.navigation.addEventListener).toBe('function');
});Manual QA Checklist
- Click a same-origin link → URL updates, no reload, UI renders.
- Press browser Back → URL reverts, scroll position restored (if
scroll: 'manual'used correctly). - Submit a POST form → no reload, server response rendered.
- Use
navigation.navigate()programmatically → central handler invoked. - Cross-origin link click → full reload as expected.
DevTools Debugging
Chrome DevTools shows navigation intercepts in the Application > Navigation panel (experimental). Set a breakpoint inside your handler() callback to step through async fetch and render.
Graceful Degradation Strategy
For unsupported browsers:
- Serve a full-SSR fallback (each route is a server-rendered page; links are plain
<a>tags). - Polyfill minimally: use History API for push/pop routing.
- Note: there is no true polyfill for Navigation API. Design your app to assume History API as the floor.
Known Limitations
- First load:
navigatedoes not fire on initial page load. SSR apps handle this naturally; CSR apps must invoke aninit()on startup. - Single-frame scope: The API operates within one browsing context. Navigations inside
<iframe>are not visible. - No history reordering: You cannot remove or rearrange entries. Temporary modals that should not persist in history require careful state design.
Performance Considerations
- Fetch during intercept: Loading content before committing the URL can increase perceived latency if the fetch fails. Consider optimistic UI updates with rollback on error.
- Avoid nested intercepts: Do not call
navigation.navigate()from insidehandler()unless you handlefinishedpromises carefully to avoid loops. - Memory: History entries accumulate. Use
entry.disposeevent to clean caches tied to disposed entries:
entry.addEventListener('dispose', () => {
cache.delete(entry.key);
});Best Practices Summary
- Single source of truth: Handle all navigations in one
navigatelistener. Do not mix with manualpushStatecalls. - Use
scroll: 'manual': Always defer scroll restoration until after async rendering completes. - Leverage state: Store view state (filters, expanded sections) on history entries for proper back/forward behavior.
- Check
canIntercept: Respect cross-origin and download navigations—do not force intercept. - Integrate View Transitions: Wrap DOM updates in
document.startViewTransition()for smooth, built-in animations. - Plan for legacy: Provide a History API fallback or SSR baseline for unsupported browsers.
References
- MDN Web Docs, Navigation API
- web.dev, Navigation API - a better way to navigate, is now Baseline Newly Available
- WICG, Navigation API Explainer
- Can I use, Navigation API support table
- MDN, NavigateEvent.intercept()
- MDN, View Transitions API