liveBook · Manning

History API

As explained in Vanilla Web

The History API is a browser API for manipulating session history entries and navigating between document URLs without necessarily loading new documents.

The History API lets an application change the current tab’s session history without necessarily loading another document. In client-side routing, it is a widely supported fallback to the Navigation API: the application updates the URL, then renders the route in the document already open. section 10.3 section 10.3.6

Three pieces form the basic routing contract:

  • Call history.pushState() for a new entry, or history.replaceState() to update the current one. Push when Back should return to the previous route; replace when correcting or normalizing the current URL. section 10.3.6 section 11.2
  • Render the new route immediately after either call. Neither call fires popstate. section 11.2
  • Listen for window’s popstate event and render from location when the user traverses Back or Forward. section 10.3.6
function renderFromLocation() {
  const route = matchRoute(location.pathname);
  renderRoute(route);
}

window.addEventListener("popstate", renderFromLocation);

This small rendering path reads the current pathname and also handles later Back or Forward traversal. A pushState() or replaceState() call must invoke that path separately. section 11.2

Intercept an internal link

Start with a real <a href>. For an ordinary same-origin application link, prevent the default click, push its path, query, and hash, then render from location. Let the browser handle modified clicks, other mouse buttons, external links, downloads, other targets, and document-fragment jumps. This preserves expected link behavior instead of turning every click into a route change. section 10.3.6 section 10.5

Session history is not an inspectable list of URLs: history.length gives its size, but the History API cannot enumerate entries. Keep shareable routes in real URLs, and configure the server to serve valid application deep links while retaining normal asset, API, and 404 behavior. A History API fallback can reproduce common same-document routing, not every detail of the Navigation API. section 10.3.1 section 10.5 section 10.3.6

How Vanilla Web covers it

How deep it goes
Works through pushState(), replaceState(), popstate, and link interception, while noting that a fallback cannot reproduce every Navigation API detail.
Examples
Uses an internal-link click handler, a popstate rendering function, and push-versus-replace route decisions.
What it assumes
Assumes familiarity with links and JavaScript event handlers; introduces the history calls needed for a routing fallback.
What you can do after
Build it from scratch as a fallback router that updates URLs, renders routes, and responds to Back and Forward.
How it connects
Connects session history to client-side routing, the Navigation API, real links, deep links, and route rendering.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.