Part of Series: Javascript Handbook

How the Javascript History API Works

📣 Sponsor

In front end Javascript, we can quite easily access the user's web history from the current location. That means we can use functions to make the user go back and forward with just Javascript.

How to navigate for the user

We have a few functions we can use to force a user to navigate to a specific page. They can all be accessed via window.history.

Going back and forward

We can make a user's browser go back or forward using the back() and forward() functions respectively. So if we want a user's browser to navigate back, we would write:


Similarly, we can go forward like this:


We can also go forward and back by a certain number by simply using go. Below we have two examples, one which goes back 5 pages, and another which goes forward by 3:

// Go back 5 pages window.history.go(-5); // Go forward 3 pages window.history.go(3);

Running these functions will force a page refresh. If we don't want a page refresh, we have to use other functions.

Pushing and Replacing History

If we want to avoid a page refresh, we can push a new history entry to the user's browser with pushState, or replace the current history entry with another using replaceState. The only difference is that with pushState, the user can go back, and with replaceState, the user cannot.

Both take 3 inputs:

  • The State - an object which is passed as data to the new page.
  • The Title - the new title for this new history state.
  • The URL (optional) - the URL to go to, which must be of the same origin.

An example is shown below:

window.history.pushState({}, "New Page Title", "/somePage");

Note: changing the page state by pushing or replacing it, does not navigate to the URL you provide. It simply updates the title and URL in the browser - while passing on the state data. If we want to navigate without a refresh, it requires a little more work.

Accessing the state object

You'll note that we passed an object above to the new history entry. To access that data, we need to use the popstate event. When the history changes, this event will fire. For example:

window.history.pushState({ someData : "someValue" }, "New Page Title", "/somePage"); window.addEventListener('popstate', function (e) { // To get the object { someData : "someValue" } when the history changes // we can use e.state console.log(e.state); });

Note:, a major point of confusion is that popstate does not fire simply by calling pushState or replaceState. The history entry will contain the state data, but it will only be fired when a user clicks back or forward. Therefore we cannot use popstate to track pushState/replaceState.


The Web History API gives us a lot of freedom over manipulating history. We can even get to a place where user's no longer have to refresh the page when clicking links, by using the fetch API to get the content of the next page.

As such, the Web History API is an important part of anyone's Javascript knowledge.

Last Updated 1625935912945

More Tips and Tricks for Javascript

Subscribe for Weekly Dev Tips

Subscribe to our weekly newsletter, to stay up to date with our latest web development and software engineering posts via email. You can opt out at any time.

Not a valid email