Manipulate Browser History with pushState and replaceState

Why it exists

Traditional websites reload the entire page on every click, which is inefficient and loses application state. Single-Page Applications (SPAs) solve this by updating the page with JavaScript, but this breaks the user's expectation that the URL and back/forward buttons will work. The History API was created to bridge this gap.

The mental model

Think of pushState as manually adding a fake entry to the browser's history log. You're telling the browser, "We didn't actually load a new page from the server, but please change the URL in the address bar and remember this state. If the user hits 'back', let me know so I can handle it."

How it works

In an SPA, when a user clicks a link, your JavaScript code prevents the default page load. It then fetches the necessary data, updates the page content, and calls history.pushState(stateObject, "", "/new-url"). This changes the URL in the address bar and adds an entry to the session history without a network request for a new page. replaceState works similarly but modifies the current history entry instead of adding a new one. When the user navigates with the back or forward buttons, the browser fires a popstate event, which your app must listen for to render the correct view for that history entry.

When to use it

Use this API in Single-Page Applications (React, Vue, Angular, etc.) to create a seamless user experience. It's essential for implementing client-side routing, enabling deep linking (sharing a URL to a specific view), and making the browser's back and forward buttons behave as expected.

When not to use it

Avoid this API in traditional multi-page websites where each URL corresponds to a distinct HTML file served from a server; the browser handles history automatically in that case. Critically, do not use pushState if you are not prepared to also implement a listener for the popstate event, as this will break the back button.

One canonical example

A user is viewing a product list at myspa.com/items. They click a category filter for "shoes". The app prevents a page reload, fetches the filtered items, updates the list in the DOM, and calls history.pushState({}, "", "/items?category=shoes"). The URL updates. If the user then clicks the back button, a popstate event fires, and the app's router must detect the old URL (/items) and re-render the original, unfiltered list.