Skip to content

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, call preventDefault(), manually invoke history.pushState(), and then update the DOM.
  • Separately listen for popstate to handle browser back/forward buttons.
  • Miss certain navigation types (e.g., programmatic location.href changes, some form submissions).
  • Inability to read the full history stack or edit non-current entries.
  • Inconsistent popstate behavior—does not fire on pushState/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: canIntercept is false. 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 after handler() resolves.
  • navigation.onnavigateerror: fires if handler() 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 its NavigationHistoryEntry.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

  1. Click a same-origin link → URL updates, no reload, UI renders.
  2. Press browser Back → URL reverts, scroll position restored (if scroll: 'manual' used correctly).
  3. Submit a POST form → no reload, server response rendered.
  4. Use navigation.navigate() programmatically → central handler invoked.
  5. 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

  1. First load: navigate does not fire on initial page load. SSR apps handle this naturally; CSR apps must invoke an init() on startup.
  2. Single-frame scope: The API operates within one browsing context. Navigations inside <iframe> are not visible.
  3. 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 inside handler() unless you handle finished promises carefully to avoid loops.
  • Memory: History entries accumulate. Use entry.dispose event 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 navigate listener. Do not mix with manual pushState calls.
  • 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