Working with the History API - Web APIs | MDN

HTML: Markup language
CSS: Styling language
JavaScript: Scripting language
Web APIs: Programming interfaces
Learn web development
Get to know MDN better
The History API enables a website to interact with the browser's session history: that is, the list of pages that the user has visited in a given window. As the user visits new pages, for example by clicking links, those new pages are added to the session history. The user can also move back and forth through the history using the browser's "Back" and "Forward" buttons.
The main interface defined in the History API is the History interface, and this defines two quite distinct sets of methods:
Methods to navigate to a page in the session history:
Methods to modify the session history:
In this guide, we'll cover only the second set of methods.
The pushState() method adds a new entry to the session history, while the replaceState() method updates the session history entry for the current page. Both these methods take a state parameter which can contain any serializable object. When the browser navigates to this history entry, the browser fires a popstate event, which contains the state object associated with that entry.
The main purpose of these APIs is to support websites like Single-page applications, that use JavaScript APIs such as fetch() to update the page with new content, instead of loading a whole new page.
Traditionally, websites are implemented as a collection of pages. When users navigate to different parts of the site by clicking links, the browser loads a whole new page each time.
While this is great for many sites, it can have some disadvantages:
For these reasons, a popular pattern for web apps is the single-page application (SPA). When a user clicks a link, the SPA performs the following steps:
In this click handler, if the link contains a data attribute "data-creature", then we use the value of that attribute to fetch a JSON file containing the new content for the page.
The JSON file might look like this:
Our displayContent() function updates the page with the JSON:
The problem is that it breaks the expected behavior of the browser's "Back" and "Forward" buttons.
From the user's point of view, they clicked a link and the page updated, so it looks like a new page. If they then press the browser's "Back" button, they expect to go to the state before they clicked the link.
But as far as the browser is concerned, the last link didn't load a new page, so "Back" will take the browser to whichever page was loaded before the user opened the SPA.
This is essentially the problem that pushState(), replaceState(), and the popstate event solve. They enable us to synthesize history entries, and to be notified when the current session history entry changes to one of these entries (for example, because the user pressed the "Back" or "Forward" buttons).
We can add a history entry to the click handler above as follows:
Here, we're calling pushState() with three arguments:
Suppose the user performs the following steps:
Now the new current history entry is A, so the browser fires the popstate event, and the event handler argument includes the JSON that we passed to pushState() when we handled the navigation to A. This means we can restore the correct content with an event handler like this:
There's one more piece we need to add. When the user loads the SPA, the browser adds a history entry. Because this was an actual page load, the entry has no state associated with it. So suppose the user does the following:
Now we want to go back to the SPA's initial state, but since this is a navigation in the same document, the page will not be reloaded, and since the history entry for the initial page has no state, we can't use popstate to restore it.
The solution here is to use replaceState() to set the state object for the initial page. For example:
On page load, we collect all the parts of the page that we need to restore when the user returns to the starting point for the SPA. This has the same structure as the JSON we fetch when handling other navigations. We pass this initialState object into replaceState(), which effectively adds the state object to the current history entry.
When the user returns to our starting point, the popstate event will contain this initial state, and we can use our displayContent() function to update the page.
You can find this complete example at https://github.com/mdn/dom-examples/tree/main/history-api, and see the demo live at https://mdn.github.io/dom-examples/history-api/.
This page was last modified on Aug 1, 2025 by MDN contributors.
Your blueprint for a better internet.
Portions of this content are ©1998–2026 by individual mozilla.org contributors. Content available under a Creative Commons license.