liveBook · Manning

History.pushState()

As explained in Vanilla Web

history.pushState() adds a session-history entry with optional state and URL without loading a new document.

Use history.pushState() when a same-document router needs to add a session-history entry without loading a new document. It can attach state and update the URL. Use history.replaceState() instead when the current entry should be updated rather than adding another. section 10.3.6 section 11.2

Changing the URL is not the same as rendering a route. pushState() does not fire popstate, so render from location immediately after calling it. Listen for popstate separately to render after Back or Forward traversal. section 10.3.6 section 11.2

Keep the fallback narrow and preserve normal browser navigation:

  • Start with real links. Intercept only same-origin application links; leave external links, downloads, other targets, modifier-key clicks, and hash jumps to the browser. section 10.3.6 section 15.4
  • For navigation initiated by code, put pushState() and the subsequent render in one helper rather than scattering calls throughout the application. section 11.2

Navigate after a save

After a form saves, a routing helper can add the destination with pushState() and then render from location. If the destination should replace the current entry, use replaceState(). When the Navigation API is available, the same helper can delegate to navigation.navigate() instead. section 11.2

Table 11.1 Deciding on storing state data in URL or in history entry

State

Belongs in the URL

Belongs in history entry state

Selected product

Yes, as /products/42.

No, because the route should be shareable.

Search filters

Usually, as query parameters.

Only if the filters are private or temporary.

Scroll position inside a panel

No.

Yes, because it belongs to the current browsing session.

Open disclosure panel

Maybe, if it should be shareable.

Yes, if it is only UI convenience.

Choose the URL for shareable route data, and history-entry state for temporary browsing-session details such as a panel’s scroll position. section 11.2

How Vanilla Web covers it

How deep it goes
Explains push versus replace, popstate behavior, manual rendering, and link-interception constraints; does not detail browser internals.
Examples
Uses an internal-link fallback, a post-save navigation helper, and a table distinguishing URL data from history-entry state.
What it assumes
Assumes real links and a route-rendering function; introduces the pushState(), replaceState(), and popstate responsibilities needed for a fallback.
What you can do after
Build it from scratch as a History API routing fallback that updates the URL, renders immediately, and handles later traversal.
How it connects
Connects session history, popstate, same-document routing, real links, and the Navigation API.

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.