Using the Browser History API

Check out my books on Amazon at https://www.amazon.com/John-Au-Yeung/e/B08FT5NT62

Subscribe to my email list now at http://jauyeung.net/subscribe/

To navigate back and forth between pages, we can use the History API that comes with most modern browsers.

In this article, we’ll look at how to use it to navigate between pages of the same origin.

Methods in the History API

The History API has a few methods to move back and forth between pages.

There’s the back method to go back to the previous page.

For example, we can use it as follows:

window.history.back()

This is the same as clicking the back button on the browser.

We can go forward by using the forward method as follows:

window.history.forward()

Moving to a Specific Point in History

We can use the go method to load a specific page from session history, identified by its relative position on the current page.

The current page is 0, so a negative integer is the pages before and a positive number is the pages after.

For example:

window.history.go(-1)

is the same as calling back().

and:

window.history.go(1)

is the same as calling forward() .

Calling go with no argument or 0 is the same as refreshing the page.

Photo by Giammarco Boscaro on Unsplash

pushState

The pushState method let us go to the page with the specified URL. It takes 3 arguments. They are:

• state — this is a Javascript object which is associated with the new history entry created by pushState() . The state object can be anything that can be sanitized. It’s saved onto the user’s disk so that it can be restored when the user restarts the browser. If the state object has a serialized representation that’s bigger than itself, then this method will throw an exception.
• title — most browsers ignore this string parameter.
• url — the new history entry’s URL. The browser won’t attempt to load the URL after calling pushState . However, it might load when we restart the browser. The URL can be absolute or relative. The URL must be the same origin as the current URL. Otherwise, an exception will be thrown.

We don’t have to change the URL if we don’t want to. Whatever it is, it must be in the same origin as the current URL.

For example, we can use it as follows:

window.onpopstate = function(event) {
  console.log(
    `location ${document.location} state ${JSON.stringify(event.state)}`
  );
};

window.history.pushState(
  {
    foo: "bar"
  },
  "",
  "/foo"
);

window.history.pushState(
  {
    bar: "baz"
  },
  "",
  "/bar"
);

window.history.back();
window.history.back();
window.history.go(2);
window.history.go(-2);

Then we get:

location https://ib3i4.csb.app/foo state {"foo":"bar"}
location https://ib3i4.csb.app/bar state null
location https://ib3i4.csb.app/bar state {"bar":"baz"}
location https://ib3i4.csb.app/bar state null

from the console.log .

onpopstate is called whenever we navigate between pages.

When we go back, we get the state logged only the first time.

Likewise, when we go forward, we get the state only logged once.

replaceState

The replaceState method is similar to pushState, but it modifies the current history entry instead of adding a new one.

It takes the same arguments as the pushState.

For example, we can use it as follows:

window.onpopstate = function(event) {
  console.log(
    `location ${document.location} state ${JSON.stringify(event.state)}`
  );
};

window.history.pushState(
  {
    bar: "bar"
  },
  "",
  "/foo"
);

window.history.go(0);

window.history.replaceState(
  {
    bar: "baz"
  },
  "",
  "/bar"
);

window.history.go(0);

Then we get:

location https://ib3i4.csb.app/foo state {"bar":"bar"}
location https://ib3i4.csb.app/bar state {"bar":"baz"}

As we can see, the entry of /bar ‘s state went from {“bar”:”bar”} to {“bar”:”baz”} once we refreshed it the second time, so the state was replaced.

Conclusion

We can use the History API by calling the methods in the window.history object.

We can go forward in history with forward, backward with back. To go to any page in history, we can call go with a number.

Also, we can call pushState to push a new entry to the history without going to it immediately. It can load the page on restart or when we call the methods above.

We can use replaceState to replace the current history entry. It takes the same arguments as pushState .

Every page must be of the same origin when using this API.