My Journal



HTML5 History API

Moving from page to page is typically well-handled in the browser. The browser stores information from previously visited pages and will redirect the user back if needed. In a recent project, I found that this wouldn’t be so easy. The content of my project was loaded using Ajax. The problem with Ajax is that it doesn’t store the history because it doesn’t load new pages every time data is requested. Fortunately, the HTML5 History API was created for just this purpose.

Working with this API was a bit of a struggle at first. Most of the information that I found online was very broken and I ended up spending half of my time just looking through enough resources to finally make sense of it. I would like to provide a cheat-sheet of sorts with the hope that this helps someone who is also receiving mixed information.

The History API provides many methods, but the 3 that I’m focusing on are: history.pushState(), history.replaceState(), and window.onpopstate().

All three of these methods directly manipulate the history stack. The history stack is a list of visited pages that the browser stores. The most recently visited page is saved on the top of this stack, and is easiest to access, with just a click of the browser’s back button.

history.pushState() and history.replaceState() are both very similar in that they allow us to manipulate the history stack.

Both of these methods take in the same 3 parameters: state, title, url.

1) State. The state can store data about the Ajax request that was made. This is extremely helpful when the user decides to revisit the site and reloads the data. This parameter typically accepts JSON data.

2) Title. Not currently supported in any of the major browsers, the title parameter changes the title of the webpage when you revisit. Note: placing an empty string in this parameter is just fine.

3) URL. This parameter accepts a URL that is wished to be display when the user revisits a site. This URL must be from the origin as the current URL. Although the browser does not load this URL when the user revisits the site using the forward or back button, it will however, use this URL if the user attempts to reload the page.

The sole difference between these two methods is that history.pushState() adds a new entry into the history stack. history.replaceState(), on the other-hand, overwrites the current history value. This is very useful if we want to change the state in response to some user action.

At this point, we have updated the history stack for each Ajax request. Now what happens if we wish to move through the session history using the back and forward buttons? Unfortunately, what we have done will not really help us out here. We have just set up the history, but not yet told our program what to do with it. For this we use window.onpopstate.

The window.onpopstate listens for every time the history changes. This event handler takes in a function to run whenever the event is fired. Now the state from either the history.pushState() or history.replaceState() will be useful. We are able to use the state parameter from the either history.pushState() or history.replaceState() to call information and execute the appropriate commands. Please note that not all browsers support the HTML5 History API. It is always best to check compatibility first with Modernizr and use history.js as a substitute, if needed.

Leave A Comment