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:


window.history.back();

Similarly, we can go forward like this:


window.history.forward();

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.

Conclusion

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