Working with the History API in HTML5

By Vipul Patel

HTML5 provides a standardized way to interact with browser history in a scripted fashion. Our browsing patterns and today's rich media content means that our browsers are working more than ever before to fetch the content and display to the user. URLs are increasingly becoming critical pieces of information, be they part of a user's bookmarks or as a link one shares on their Linkedin/Facebook profile.

The ability to add entries to the browser history and change the URL displayed in the browser bar is something new introduced as part of the history API in the HTML5 specification.

Historically, every new URL in the browser location bar represents a full page refresh. This can be pretty resource intensive if the web page contains rich media. HTMl5 seeks to eliminate that by the history API.

The HTML5 specification says…

Before we dig deeper on the problems that the history API solves, let us take a quick look at the History interface mentioned in the HTML5 specification at http://www.w3.org/html/wg/drafts/html/master/browsers.html#history .

interface History {
 readonly attribute long length;
 readonly attribute any state;
 void go(optional long delta);
 void back();
 void forward();
 void pushState(any data, DOMString title, optional DOMString? url = null);
 void replaceState(any data, DOMString title, optional DOMString? url = null);


We can see that there are a few APIs and a few properties. We will dig deeper into them later on.


How History API helps

When we have pages which are nearly similar in content, every refresh presents wasted effort (bandwidth/processing/etc.). The history API enables smarter way to download only the portion of the page which is different from the current page (by using scripts)

By fetching only the differentiated content from the new location, swapping the changed content current displayed in the browser and updating the browser location bar with the new URL, we can potentially save a lot of network calls and also provide performance boost to the user experience, while preserving the user browse history.


Support for history API by a particular browser can be checked by looking at both window.history property and history.pushState. If a browser reports positive on both counts, then it supports the history API.


To add entry to the browser history and the location in the browser address bar, the history.pushState API can be called.

window.history.pushState(objectStateData, "string", "URL");


The above APIs takes in three arguments - first, an object which can contain state data, second, the title of the web page, and third, the URL to be shown in the browser address bar.


Hands On


For the purpose of the demo, we are loosely basing our sample snippet to the example provided in the HTML5 specification.


<!DOCTYPE html>

<title>Number Game - 10</title>

<p>You are at coordinate <span id="coord">0</span></p>


<a href="?x=11" onclick="go(1); return false;">Forward to 11</a> or

<a href="?x=9" onclick="go(-1); return false;">Back to 9</a>?



var currentNumber = 0; // prefilled by server

function go(d) {

setupPage(currentNumber + d);

history.pushState(currentNumber, document.title, '?x=' + currentNumber);


onpopstate = function (event) {



function setupPage(page) {

currentNumber = page;

document.title = 'Current number - ' + currentNumber;

document.getElementById('coord').textContent = currentNumber;

document.links[0].href = '?x=' + (currentNumber + 1);

document.links[0].textContent = 'Forward to ' + (currentNumber + 1);

document.links[1].href = '?x=' + (currentNumber - 1);

document.links[1].textContent = 'back to ' + (currentNumber - 1);



In the above code snippet, on every click, we are executing the function "go" which, in additional to updating the page to reflect the number progress, also uses the history.pushState API to add activities to the browser history as well as update the location in the address bar.

If you watch the activities in a web debugger, you will notice that no new HTML is being fetched; however, the browser seems to think it has visited a bunch of web pages. That is the history API in action.


In this article, we learned basics behind the history API. I hope you have found this information useful.


About the author

Vipul Patel is a Program Manager currently working at Amazon Corporation. He has formerly worked at Microsoft in the Lync team and in the .NET team (in the Base Class libraries and the Debugging and Profiling team). He can be reached at vipul.patel@hotmail.com




  • Web Development Newsletter Signup

    Invalid email
    You have successfuly registered to our newsletter.
Thanks for your registration, follow us on our social networks to keep up-to-date