History API & State Management

The browser History API is the low-level machinery that lets a single-page application change the address bar, attach state to navigation entries, and respond to the back and forward buttons without ever issuing a full page request. Everything a client-side router does — from intercepting a link click to restoring a scroll position — ultimately resolves to a small set of methods and one event defined by this API. Understanding those primitives precisely is what separates a router that feels native from one that quietly breaks the back button.

The Mental Model

The clearest way to think about the History API is to treat the browser’s session history as a stack of entries, where each entry pairs a URL with a serialisable state object. Navigating forward pushes a new entry; navigating back pops the cursor to a previous one. Your application never owns this stack directly — the browser does — but it can mutate the top of it and observe when the cursor moves.

Four concerns sit on top of that stack and constantly reference each other. URL mutation (pushState, replaceState) writes new entries or rewrites the current one. The popstate event is the browser telling you the cursor moved because the user pressed back, forward, or swiped. Scroll restoration is the question of where the viewport should sit after that cursor moves, and it feeds scroll restoration logic on every popstate. Deep linking is the inverse problem: reconstructing full application state from a URL that was typed, bookmarked, or shared cold, which is handled by your deep linking implementation.

The unifying insight is that the URL plus the history state object together form a serialisable snapshot of where the user is. If you can serialise enough into that snapshot to rebuild the view, then back, forward, refresh, and share-the-link all become the same operation: read a snapshot, render it. This is also why client-side routing cannot be designed in isolation — it is one corner of a broader routing architecture and is realised differently across framework-specific routing patterns. Where those approaches differ is mostly in how much they hide this stack from you.

A critical asymmetry shapes everything downstream: programmatic navigation and user navigation are not symmetric. When you call pushState, you already know the destination, so no event fires. When the user navigates, the browser fires popstate and hands you back the state you previously stored, expecting you to reconstruct the view. Keeping the URL bar, the history stack, and your in-memory state mutually consistent across both paths is the entire discipline of state management here.

It helps to contrast this with the model it replaced. In a traditional multi-page application, the browser owns the entire loop: a click triggers a request, the server returns a new document, the old document is torn down, scroll resets, focus resets, and the title updates — all for free, all consistent by construction. A single-page application trades that built-in consistency for speed and continuity, and in doing so inherits every responsibility the browser used to handle. The History API is the surface where you re-assume those duties one by one. Each thing that “just worked” before — the back button, scroll position, the announced title, the indexable URL — now becomes an explicit line of code, and forgetting any one of them produces a subtly broken experience rather than an obvious error.

Two distinctions are worth fixing early because they recur throughout the design. The first is append versus replace: pushState is for transitions a user should be able to reverse with the back button (moving between pages or views), while replaceState is for refinements of the current view that should not grow the stack (applying a filter, updating a query parameter, recording the current scroll position). Choosing wrongly here is the difference between a back button that returns to the previous page and one that cycles uselessly through twenty filter states. The second distinction is state versus URL: the URL is the canonical, shareable, crawlable address, while the state object is private, ephemeral context the browser carries alongside it. Anything another person must be able to reproduce belongs in the URL; anything that is merely an optimisation for your session — a cached scroll offset, a transition direction hint — belongs in state.

The session history stack Three history entries pair a URL with a state object; pushState adds an entry, replaceState swaps the top, and popstate moves the active cursor. The session history stack /products state: list view /products/42 state: detail /cart active entry pushState adds an entry, replaceState swaps the top, popstate moves the cursor
The browser owns the stack; your code mutates the top and observes the cursor.

Browser Primitives & Spec Reference

The HTML Living Standard defines the History interface, accessible as window.history. The two mutation methods share a signature:

// TypeScript 5.x — built-in lib.dom.d.ts signatures
interface History {
  pushState(data: unknown, unused: string, url?: string | URL | null): void;
  replaceState(data: unknown, unused: string, url?: string | URL | null): void;
  readonly state: unknown;
  scrollRestoration: 'auto' | 'manual';
  back(): void;
  forward(): void;
  go(delta?: number): void;
  readonly length: number;
}

pushState(data, unused, url) appends a new entry to the session history with the supplied state and URL, leaving the document untouched. replaceState is identical except it overwrites the current entry rather than appending. The second parameter, historically named title, is unused by every shipping browser — pass an empty string. The url argument is resolved relative to the current document and must be same-origin; a cross-origin value throws a SecurityError.

The data argument is copied using the structured clone algorithm, not JSON.stringify. Structured clone supports more than JSON — Date, Map, Set, ArrayBuffer, and typed arrays survive — but it rejects functions, DOM nodes, and class instances with behaviour, throwing DataCloneError. The clone is also stored, so later mutating the original object does not affect the entry.

history.state returns the structured-clone copy associated with the current entry, or null if none was set. On a cold page load it reflects whatever state was attached to that entry, which is why reading it during initialisation is the correct way to rehydrate.

The PopStateEvent interface carries a single relevant property, event.state, equal to the new current entry’s state after the cursor moves. Per spec, popstate fires for history traversal — back, forward, history.go() — but explicitly not for pushState or replaceState. It also does not fire for same-document fragment navigation, which dispatches hashchange instead.

history.scrollRestoration is a writable property toggling between 'auto' (the browser restores scroll position on traversal) and 'manual' (you take full responsibility). Setting it to 'manual' is the prerequisite for any custom restoration strategy.

history.length reports the number of entries in the session history, but it is a coarse and often misleading signal — it includes entries from before your application loaded and is capped by the browser, so it cannot be used to reliably detect “is there a previous page within my app”. For that, store a depth counter in your own state. The back(), forward(), and go(delta) methods move the cursor programmatically and do fire popstate, because they are traversals rather than mutations; go(0) is a no-op reload-free refresh of the current entry.

The modern Navigation API (window.navigation) supersedes much of this with a single navigate event that fires for all same-document navigations, including programmatic ones, plus an intercept() method, a unified navigation.entries() list, and promise-returning navigation methods. It collapses the firing asymmetry that causes most History API bugs: because navigate fires for both user and programmatic navigation, you write a single handler instead of two divergent code paths. It also exposes navigation.canGoBack and navigation.canGoForward, the reliable answer to the question history.length cannot give. As of 2026 it remains Chromium-only, so the History API stays the portable baseline, but writing your router so the navigation logic is isolated behind a small adapter lets you adopt the Navigation API where available without rewriting the application.

Architecture Overview

A minimal client-side history router has four responsibilities: intercept in-app link clicks, push a new entry, render the matching view, and rebuild the view when popstate fires. The annotated implementation below shows the full loop.

// TypeScript 5.x — framework-agnostic history router
type RouteState = { scrollY?: number; [key: string]: unknown } | null;
type Renderer = (path: string, state: RouteState) => Promise<void>;

export class HistoryRouter {
  private isNavigating = false;

  constructor(private render: Renderer) {
    history.scrollRestoration = 'manual'; // we own scroll restoration

    // 1. Intercept clicks on same-origin links and convert to pushState.
    document.addEventListener('click', this.onClick);

    // 2. Respond to back/forward — the only signal for user navigation.
    window.addEventListener('popstate', this.onPopState);

    // 3. Rehydrate the entry the page loaded on (deep link / refresh).
    void this.render(location.pathname, history.state as RouteState);
  }

  private onClick = (event: MouseEvent) => {
    const anchor = (event.target as Element).closest('a');
    if (!anchor || event.defaultPrevented) return;
    // Honour modifier keys and external/target links — never hijack them.
    if (event.metaKey || event.ctrlKey || event.shiftKey || anchor.target) return;
    const url = new URL(anchor.href);
    if (url.origin !== location.origin) return;

    event.preventDefault();
    void this.navigate(url.pathname, { scrollY: 0 });
  };

  async navigate(path: string, state: RouteState): Promise<void> {
    // pushState does NOT fire popstate, so render explicitly here.
    history.pushState(state, '', path);
    await this.render(path, state);
  }

  private onPopState = async (event: PopStateEvent) => {
    if (this.isNavigating) return; // guard against overlapping traversals
    this.isNavigating = true;
    try {
      await this.render(location.pathname, event.state as RouteState);
    } finally {
      this.isNavigating = false;
    }
  };
}

The two render paths — explicit after navigate, and event-driven on popstate — are deliberately distinct because of the firing asymmetry. The matching of location.pathname against view handlers is its own subject; see route matching algorithms for how patterns and dynamic segments resolve to handlers.

Several design decisions in that code are load-bearing. The click handler delegates from document rather than binding to each anchor, so links rendered after initialisation are handled without re-wiring — essential in an application whose DOM is constantly replaced. The same handler bails out early on modifier keys, on target attributes, and on cross-origin hrefs, deliberately not intercepting cases where the browser’s default behaviour is correct; a router that hijacks Cmd-click or external links feels broken even though no error is thrown. Setting scrollRestoration = 'manual' in the constructor is what makes the router, not the browser, the authority on viewport position, which is the precondition for the strategies in the scroll restoration topic working at all.

The isNavigating guard deserves attention because it addresses a real race. A user holding the back button, or a trackpad swipe that fires several popstate events in quick succession, can begin a second render before the first — which may be awaiting data — has finished, leaving the DOM reflecting one URL while the address bar shows another. The simple boolean lock shown here drops overlapping traversals; a more sophisticated router cancels the in-flight render with an AbortController instead, so the latest navigation always wins. Either way, the principle is that asynchronous rendering and synchronous history mutation must be reconciled, because the history stack moves the instant the user acts whether or not your data has arrived.

One subtle requirement is establishing initial state. On a cold load the entry the page arrived on has null state, so a defensive router calls replaceState once during initialisation to seed a known shape — for example { scrollY: 0 } — guaranteeing that the first popstate back to this entry returns a usable object rather than null. This pairs naturally with the rehydration read in the constructor: read what is there, normalise it, and write it back so every entry the application creates carries a consistent state contract.

Performance & SEO Implications

History state is not free storage. Each entry’s state object is serialised and held by the browser, and implementations cap its size. Firefox documents a hard limit around 16 MiB; Safari has historically thrown at roughly 640KB, the most restrictive ceiling you should design against. Exceeding the limit throws a DataCloneError or QuotaExceededError depending on the engine. The practical rule is to store reference IDs and view coordinates, never full datasets — keep the snapshot small enough to rebuild from, and refetch the payload from cache or network.

For discoverability, URLs produced by pushState are real, indexable URLs because they are same-origin paths the server can be asked to serve. The catch is that a crawler requesting one cold must receive meaningful HTML, which means the server needs a fallback that returns the application shell or a pre-rendered document for any valid path. Without that, deep-linked routes return 404s or empty shells; the broader trade-offs are covered under SPA versus MPA trade-offs and the server side under fallback routing strategies.

Hydration timing is the third performance axis. When server-rendered HTML is paired with a client router, the router must read history.state and location and reconcile them with the already-painted DOM before attaching listeners, or the first interaction races the hydration pass. Deferring pushState calls until after hydration completes, and treating the initial render as a read rather than a navigation, avoids the most common class of hydration mismatch.

There is also a measurable interaction with Core Web Vitals. Because client-side navigation does not reload the document, it does not reset the Cumulative Layout Shift accounting the way a full navigation does; a route transition that injects content and then restores scroll asynchronously can register as layout shift attributed to the current page. Restoring scroll within a single frame after the new content has laid out, rather than across multiple frames, keeps these transitions out of the CLS budget. Likewise, keeping the history state payload small directly benefits the responsiveness metric: serialising a large object on every replaceState during scroll (a common scroll-tracking pattern) can block the main thread enough to show up as input delay, which is another reason to throttle those writes and keep them tiny.

A final SEO subtlety concerns canonicalisation. Because pushState can produce many URLs that render the same logical view — trailing slashes, query-parameter ordering, tracking parameters — each route render should also reconcile the document’s <link rel="canonical"> so crawlers consolidate ranking signals onto one address rather than treating every variant as a distinct page. This is a server-and-client shared concern: the server emits the canonical for cold loads, and the client updates it on every subsequent navigation.

Accessibility Considerations

A full page load gives assistive technology a free reset: focus returns to the document and the screen reader announces the new title. Client-side navigation provides none of this, so the router must recreate it manually, or back-button navigation becomes silent and disorienting for screen reader and keyboard users.

Two mechanisms cover the gap. First, move focus deliberately after each render — typically to the main landmark or the new page’s first heading, using element.focus() with tabindex="-1" on a non-interactive target so keyboard users land in the new content rather than at the top of an unchanged DOM. Second, announce the route change through an ARIA live region.

// TypeScript 5.x — route-change announcement and focus management
function announceRoute(title: string): void {
  let live = document.getElementById('route-announcer');
  if (!live) {
    live = document.createElement('div');
    live.id = 'route-announcer';
    live.setAttribute('aria-live', 'assertive');
    live.setAttribute('aria-atomic', 'true');
    live.style.cssText =
      'position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);';
    document.body.appendChild(live);
  }
  live.textContent = `${title}, navigated`;

  const main = document.querySelector<HTMLElement>('main');
  main?.setAttribute('tabindex', '-1');
  main?.focus({ preventScroll: true });
}

Crucially, this announcement must fire on popstate-driven navigation too, not only on click-driven navigation — a user pressing back deserves the same feedback as one clicking a link. Use aria-live="assertive" for navigation because the context change is significant enough to interrupt; reserve polite for incidental updates.

Two refinements make this robust in practice. First, update the document <title> on every render and announce that same title, so the spoken feedback matches what a sighted user sees in the tab and what shows up in browser history — consistency across modalities matters more than cleverness. Second, the live region must already exist in the DOM and be empty before the text is written into it; assistive technology only announces a change to a live region, so creating the element and populating it in the same tick can be missed. Seeding the region during initialisation and only mutating its textContent thereafter is the reliable pattern. Where focus is concerned, prefer moving focus to a heading or the main landmark over a generic skip target, and avoid stealing focus mid-transition if the user has begun interacting elsewhere, which would be more disruptive than the silence it replaces.

Common Pitfalls & Edge Cases

  • popstate does not fire on pushState/replaceState. The single most common bug: developers attach a popstate listener and expect it to catch their own programmatic navigation. It will not. Render explicitly after every pushState.
  • DataCloneError on non-serialisable state. Passing a function, DOM node, Symbol, or class instance with methods into the state argument throws immediately. Reduce state to plain serialisable values before storing.
  • State exceeding the size cap. Stuffing entire API responses into history state hits Safari’s ~640KB ceiling. Store IDs and refetch.
  • Scroll drift on traversal. Leaving scrollRestoration on 'auto' while rendering content asynchronously restores scroll before the content exists, landing the user mid-page or at the top. Set it to 'manual' and restore after layout settles.
  • The empty initial state. On a fresh load, history.state is null until you call replaceState. Code that assumes an object will throw; always handle the null case during rehydration.
  • Hijacking modified clicks. Calling preventDefault() on a click that used Cmd/Ctrl/middle-button breaks “open in new tab”. Always check modifier keys and target before intercepting.
  • hashchange versus popstate confusion. Fragment-only changes fire hashchange, not popstate. Mixing hash routing and History routing in one app requires listening to both.
  • Leaked listeners on teardown. In long-lived apps or micro-frontends, failing to remove the popstate listener on unmount accumulates handlers; use an AbortController signal when adding listeners.

Browser & Runtime Compatibility

Feature Chrome Firefox Safari Edge Node (SSR)
pushState / replaceState Yes Yes Yes Yes No (history undefined)
popstate event Yes Yes Yes Yes No
Structured clone for state Yes Yes Yes Yes n/a
history.scrollRestoration Yes Yes Yes Yes No
State size ceiling ~16 MiB ~16 MiB ~640KB ~16 MiB n/a
Navigation API (navigation) Yes No No Yes No

On the server there is no window or history, so SSR code paths must guard every access and derive the route from the incoming request URL instead. Feature-detect window.navigation before using the Navigation API, and treat the History API as the universally available fallback.

Explore the Topics

  • pushState & replaceState Usage — When to append a new entry versus rewrite the current one, with safe wrappers around the structured-clone and same-origin constraints.
  • popstate Event Handling — Wiring user back/forward navigation back into your render loop, including the firing asymmetry and race-condition guards.
  • Scroll Restoration Strategies — Taking manual control of viewport position so back navigation lands where the user left off, even on virtualised lists.
  • Deep Linking Implementation — Reconstructing complete application state from a cold URL so bookmarks, shares, and refreshes all resolve correctly.