The Navigation API: Native Browser Routing for Single-Page Applications

Why the History API Was Never Designed for SPAs

Every single-page application framework has built its own routing layer on top of the History API — pushState, replaceState, and the popstate event. React Router, Vue Router, Angular Router, and TanStack Router all perform the same fundamental work: intercept link clicks, prevent full-page reloads, update the URL, render new content, and manage scroll position. They each reinvent this wheel because the History API was designed for a different era.

The History API shipped in 2011 to solve a narrow problem: allowing AJAX applications to update the URL bar without triggering a page reload. It was never intended as a routing system. The limitations are well-documented: popstate only fires on back/forward navigation (not on pushState calls), there is no way to intercept or cancel a navigation before it happens, scroll restoration is unreliable, and there is no built-in mechanism to handle navigation errors.

The Navigation API, now Baseline across Chrome, Edge, Firefox 147+, and Safari 26.2+, is a purpose-built replacement. It provides a unified navigate event that fires on every navigation type — link clicks, form submissions, history.back(), history.forward(), and programmatic navigation calls. A single event handler replaces the fragmented listener architecture that every SPA framework has been forced to maintain.

Core Architecture: navigation.addEventListener(‘navigate’)

The Navigation API centers on a single global object, window.navigation, and a single event, navigate. Every navigation in the page — whether triggered by a user clicking an anchor tag, submitting a form, pressing the browser’s back button, or calling navigation.navigate() — fires this event before the navigation occurs.

// Minimal SPA router using the Navigation API
navigation.addEventListener('navigate', (event) => {
    // Skip navigations we cannot or should not intercept
    if (!event.canIntercept) return;      // Cross-origin navigations
    if (event.hashChange) return;          // Same-page anchor jumps
    if (event.downloadRequest) return;     // File downloads

    const url = new URL(event.destination.url);

    // Only handle same-origin navigations within our SPA
    if (url.origin !== location.origin) return;

    event.intercept({
        scroll: 'after-transition',  // Restore scroll after content loads
        async handler() {
            // Fetch and render the new page content
            const response = await fetch(url.pathname);
            const html = await response.text();

            // Parse and inject the content
            const parser = new DOMParser();
            const doc = parser.parseFromString(html, 'text/html');
            const content = doc.querySelector('#app-content');

            document.querySelector('#app-content').replaceWith(content);

            // Update the page title
            document.title = doc.title;
        }
    });
});

The event.intercept() call is where the power lies. It tells the browser: “Do not perform a full page load. Instead, update the URL immediately, and run my async handler to update the DOM.” The browser handles everything else: URL bar update, history stack entry creation, scroll position management, and focus reset.

Navigation Types and the NavigateEvent Object

The NavigateEvent provides rich context about what triggered the navigation, eliminating the guesswork that History API users dealt with constantly.

navigation.addEventListener('navigate', (event) => {
    console.log({
        // What type of navigation is this?
        navigationType: event.navigationType,
        // 'push' — new navigation (link click, navigate() call)
        // 'replace' — URL replacement (redirect, replaceState equivalent)
        // 'reload' — page reload
        // 'traverse' — back/forward button

        // Where are we going?
        destinationUrl: event.destination.url,
        destinationKey: event.destination.key,      // Unique ID for this history entry
        destinationIndex: event.destination.index,  // Position in the history stack

        // Can we intercept this navigation?
        canIntercept: event.canIntercept,  // false for cross-origin

        // Was this triggered by the user?
        userInitiated: event.userInitiated, // true for clicks, false for programmatic

        // Associated form data (for form submissions)
        formData: event.formData,  // FormData object or null

        // Navigation info (custom data passed via navigate())
        info: event.info,  // Any value passed via navigation.navigate(url, { info })
    });
});

The navigationType distinction is particularly valuable. With the History API, distinguishing a back-button press from a forward-button press from a programmatic pushState required brittle heuristics. The Navigation API classifies every navigation explicitly.

Scroll Restoration That Actually Works

Scroll restoration in SPAs has been a persistent pain point. The History API’s scrollRestoration property is a blunt instrument: either the browser controls scrolling entirely, or JavaScript does. In practice, neither approach works reliably because async content loading means the DOM is not ready when the browser attempts to restore scroll position.

The Navigation API solves this with event.intercept({ scroll: 'after-transition' }). The browser waits for the handler’s promise to resolve — meaning your async content fetch and DOM update have completed — before restoring the scroll position.

navigation.addEventListener('navigate', (event) => {
    if (!event.canIntercept) return;

    event.intercept({
        // 'after-transition': Browser restores scroll AFTER handler resolves
        // 'manual': You control scroll timing yourself
        scroll: 'after-transition',

        async handler() {
            const content = await fetchPageContent(event.destination.url);
            renderContent(content);
            // At this point, handler resolves.
            // Browser now restores scroll position for traversals,
            // or scrolls to top/fragment for new navigations.
        }
    });
});

// For complex layouts that need precise scroll control:
navigation.addEventListener('navigate', (event) => {
    if (!event.canIntercept) return;

    event.intercept({
        scroll: 'manual', // We control scroll timing

        async handler() {
            const content = await fetchPageContent(event.destination.url);
            renderContent(content);

            // Wait for images/iframes to load before restoring scroll
            await document.fonts.ready;
            await Promise.all(
                [...document.images]
                    .filter(img => !img.complete)
                    .map(img => new Promise(r => img.addEventListener('load', r)))
            );

            // NOW restore scroll — layout is fully stable
            event.scroll();
        }
    });
});

The manual scroll control via event.scroll() is critical for content-heavy pages where images and fonts cause layout shifts. Triggering scroll restoration before layout stabilizes causes the classic “scroll jumps to wrong position” bug that plagues SPA scroll restoration. The Speculation Rules API for prefetching can preload resources before navigation, minimizing the delay between intercept and scroll restoration.

Abort Signals: Cancelling In-Flight Navigations

Fast-clicking users who navigate to page A then immediately click to page B create a race condition: page A’s fetch might resolve after page B’s, overwriting the correct content. The Navigation API solves this with built-in AbortSignal integration.

navigation.addEventListener('navigate', (event) => {
    if (!event.canIntercept) return;

    event.intercept({
        async handler() {
            // event.signal is automatically aborted if a new navigation starts
            const response = await fetch(event.destination.url, {
                signal: event.signal  // Abort this fetch if user navigates away
            });

            // If we reach here, this navigation is still active
            if (event.signal.aborted) return; // Extra safety check

            const html = await response.text();
            document.querySelector('#app').innerHTML = html;
        }
    });
});

// Navigation lifecycle events for loading indicators
navigation.addEventListener('navigatesuccess', () => {
    document.querySelector('.loading-bar')?.classList.remove('active');
});

navigation.addEventListener('navigateerror', (event) => {
    document.querySelector('.loading-bar')?.classList.remove('active');
    console.error('Navigation failed:', event.error);
    // Show error UI, offer retry
});

No more tracking fetch controller references, no more stale-closure bugs, no more request deduplication logic. The browser manages the abort lifecycle automatically. The navigatesuccess and navigateerror events provide clean hooks for loading indicators and error handling — another pattern that History API users had to implement manually.

Programmatic Navigation and State Management

The navigation object provides programmatic methods that replace history.pushState() and history.replaceState() with a richer, promise-based API.

// Programmatic navigation — replaces history.pushState()
const result = await navigation.navigate('/dashboard', {
    state: { section: 'analytics', filters: { period: '7d' } },
    info: { trigger: 'sidebar-click' }, // Passed to navigate event's event.info
    history: 'push'  // 'push', 'replace', or 'auto'
});
// result.committed — Promise: URL has been updated
// result.finished  — Promise: Handler has completed

// Reading current and historical state
const currentState = navigation.currentEntry.getState();
console.log(currentState); // { section: 'analytics', filters: { period: '7d' } }

// Traversing the history stack
const entries = navigation.entries();
console.log(entries.length);           // Total history entries
console.log(navigation.currentEntry);  // Current NavigationHistoryEntry

// Navigate to a specific history entry by key
const previousEntry = entries[entries.length - 2];
await navigation.traverseTo(previousEntry.key);

// Navigate back/forward
await navigation.back();
await navigation.forward();

The state management is strictly typed and deeply cloneable — any value that survives structuredClone() can be stored. Unlike history.state, which returns the state of the current entry but provides no way to inspect other entries’ state, navigation.entries() gives read access to the full stack. The structuredClone deep copy mechanism ensures state objects are safely isolated across entries.

Form Submission Interception

The Navigation API intercepts form submissions natively — something the History API could not do without attaching separate submit event listeners to every form. When a user submits a form, the navigate event fires with event.formData populated as a FormData instance.

// Handling form submissions without page reload
navigation.addEventListener('navigate', (event) => {
    if (!event.canIntercept) return;

    // Check if this navigation was triggered by a form submission
    if (event.formData) {
        const url = new URL(event.destination.url);

        event.intercept({
            async handler() {
                // Submit the form data via fetch instead of full page POST
                const response = await fetch(url.pathname, {
                    method: 'POST',
                    body: event.formData,
                    signal: event.signal, // Auto-abort if user navigates away
                });

                if (!response.ok) {
                    const errorData = await response.json();
                    renderFormErrors(errorData.errors);
                    return;
                }

                const result = await response.json();
                renderSuccessMessage(result);

                // Optionally navigate to a success page
                // navigation.navigate('/success', { state: result });
            }
        });
        return; // Don't fall through to page navigation logic
    }

    // ... regular page navigation handling
});

This eliminates an entire category of boilerplate: no more event.preventDefault() on form elements, no more manually serializing form data, no more coordinating between form submission handlers and the router. Every navigation — whether from a link click, a form POST, or the back button — flows through the same centralized handler.

Per-Entry State and the NavigationHistoryEntry API

Each history entry in the Navigation API has a unique key (stable across the session) and an id (stable across the entry’s lifetime). The key survives page reloads — if the user navigates to /dashboard, reloads, then navigates back, the same key identifies that dashboard entry. This enables reliable state association that the History API could never provide.

// Associate data with specific history entries
const entryCache = new Map();

navigation.addEventListener('navigate', (event) => {
    if (!event.canIntercept) return;

    event.intercept({
        async handler() {
            const key = event.destination.key;

            // For traverse navigations, check if we already cached this entry's content
            if (event.navigationType === 'traverse' && entryCache.has(key)) {
                const cached = entryCache.get(key);
                renderContent(cached.html);
                document.title = cached.title;
                return; // Skip the fetch — instant back/forward
            }

            // Fresh navigation: fetch and cache
            const response = await fetch(event.destination.url, { signal: event.signal });
            const html = await response.text();
            const title = extractTitle(html);

            entryCache.set(key, { html, title });
            renderContent(html);
            document.title = title;
        }
    });
});

// Listen for entries being removed from the stack (user navigated to new branch)
navigation.addEventListener('dispose', (event) => {
    // Clean up cached data for entries that are no longer reachable
    entryCache.delete(event.entry.key);
});

The dispose event fires when a history entry is permanently removed from the stack — for example, when the user navigates back two entries then navigates forward to a new URL, the two “future” entries that were discarded fire dispose. This provides a clean mechanism for releasing cached resources, closing open connections, or cancelling pending operations associated with a specific history entry.

Building a Complete Router: Putting It All Together

// Production-ready SPA router using the Navigation API
class AppRouter {
    #routes = new Map();
    #fallback = null;

    route(pattern, handler) {
        this.#routes.set(pattern, handler);
        return this; // Chainable
    }

    fallback(handler) {
        this.#fallback = handler;
        return this;
    }

    start() {
        navigation.addEventListener('navigate', (event) => {
            if (!event.canIntercept || event.hashChange || event.downloadRequest) return;

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

            const matchedHandler = this.#matchRoute(url.pathname);
            if (!matchedHandler) return; // Let browser handle unmatched routes

            event.intercept({
                scroll: 'after-transition',
                async handler() {
                    try {
                        await matchedHandler.fn({
                            params: matchedHandler.params,
                            url,
                            signal: event.signal,
                            navigationType: event.navigationType,
                            state: event.destination.getState?.() ?? {},
                        });
                    } catch (err) {
                        if (err.name !== 'AbortError') throw err;
                    }
                }
            });
        });

        // Handle the initial page load
        const initialUrl = new URL(location.href);
        const match = this.#matchRoute(initialUrl.pathname);
        if (match) {
            match.fn({ params: match.params, url: initialUrl, signal: AbortSignal.any([]) });
        }
    }

    #matchRoute(pathname) {
        for (const [pattern, fn] of this.#routes) {
            const regex = new RegExp('^' + pattern.replace(/:(w+)/g, '(?[^/]+)') + '$');
            const match = pathname.match(regex);
            if (match) return { fn, params: match.groups || {} };
        }
        return this.#fallback ? { fn: this.#fallback, params: {} } : null;
    }
}

// Usage
const router = new AppRouter();

router
    .route('/', async ({ signal }) => {
        const data = await fetch('/api/home', { signal }).then(r => r.json());
        renderHomePage(data);
    })
    .route('/posts/:id', async ({ params, signal }) => {
        const post = await fetch(`/api/posts/${params.id}`, { signal }).then(r => r.json());
        renderPostPage(post);
    })
    .route('/dashboard', async ({ state }) => {
        renderDashboard(state);
    })
    .fallback(async () => {
        render404Page();
    })
    .start();

This entire router — route matching, scroll restoration, abort handling, error management, and back/forward support — is under 80 lines. The equivalent implementation using the History API typically requires 200–300 lines plus edge-case patches for Safari scroll behavior, popstate timing quirks, and form submission interception.

Migration Path and Framework Adoption

The Navigation API does not require abandoning your framework’s router overnight. The recommended migration path: start by using navigation.addEventListener('navigate') alongside your existing router for analytics, loading indicators, and scroll restoration. Once comfortable, gradually move route handling into the Navigation API and reduce your dependency on the framework-level router.

Framework integration is progressing. React Router v7 and TanStack Router are building Navigation API support as an underlying transport layer. The API is also particularly well-suited for server-rendered architectures using the declarative HTML patterns where page transitions should be smooth but JavaScript-heavy client-side routing is undesirable.

For progressive enhancement, feature-detect with if ('navigation' in window) and fall back to your existing History API router for older browsers. The Navigation API is Baseline Newly Available as of 2026, meaning all evergreen browsers support it, but enterprise environments with locked browser versions may still need the fallback.

The Navigation API represents the browser platform finally acknowledging that SPAs are a legitimate architectural pattern deserving first-class support, not a hack built on top of APIs designed for document navigation. For new projects, it is the recommended foundation for client-side routing.