The DOM window object provides access to the browser’s history through the history object.

Moving Forward and Backward

1
2
window.history.back()
window.history.forward()

Moving to a specific point in history

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

1
2
window.history.go(-1)
window.history.go(1)

You can determine the number of pages in the history stack by looking at the value of the length property:

1
var numberOfEntries = window.history.length

Adding and Modifying History Entries

history.pushState() and history.replaceState() methods work in conjunction with the window.onpopstate event.

Using history.pushState() changes the referrer that gets used in the HTTP header for XMLHttpRequest objects created after you change the state. The referrer will be the URL of the document whose window is this at the time of creation of the XMLHttpRequest object.

Example of pushState() Method

Suppose http://mozilla.org/foo.html executes the following JS.

1
2
3
// history.pushState(StateObj, title, URL)
var stateObj = { foo: 'bar' }
history.pushState({ stateObj, 'page 2', 'bar.html' })

This will cause the URL bar to display http://mozilla.org/bar.html, but won’t cause the browser to load bar.html or even check that bar.html exists.

Suppose now that the user now navigates to http://google.com, then click back. At this point, the URL bar will display http://mozilla.org/bar.html, and the page will get a popstate event whose state object contains a copy of stateObj.

If we click back again, the URL change to http://mozilla.org/foo.html, and the document will get another popstate event, this time with a null state object.(which is different from replaceState).

The pushState() method

pushState() takes three arguments: a state object, a title(which is currently ignored), and (optionally) a URL.

  • state object - The state object is a javascript object which is associated with the new history entry created by pushState. Whenever the user navigates to the new state, a popstate event is fired, and the state property of the event contains a copy of the history entry’s state object.

The state object can be anything that can be serialized. Because Firefox saves the state objects to the user’s disk so they can be restored after the user restarts the browser, we impose a size limit of 640k characters on the serialized representation of a state object. If you pass a state object whose serialized representation is larger than this to pushState(), the method will throw an exception. If you need more space than this, you’re encouraged to use sessionStorage and/or localStorage.

  • title - Firefox currently ingores this parameter, although it may use it in the future. Passing the empty string here should be safe against future changes to the method.

  • URL - The new history entry’s URL is given by this parameter. Note that the browser won’t attempt to load this URL after a call to pushState(), but it might attempt to load the URL later, for instance after the user restarts the browser. The new URL does not need to be absolute; if it’s relative, it’s resolved to the current URL. The new URL must be of the same origin as the current URL; otherwise pushState will throw an exception. The parameter is optional, if it isn’t specified, it’s set to the document’s current URL.

In a sense, calling pushState() is similar to setting window.location = '#foo', in that both will create and activate another history entry associated with the current document, but pushState has a few advantages:

  • The new URL can be any URL in the same origin as the current URL. In contrast, setting window.location keeps you at the same document only if you modify only the hash

  • You don’t have to change the URL if you don’t want to. In contrast, setting window.location = '#foo' only creates a new history entry if the current hash isn’t #hash

  • You can associate arbitrary data with your new history entry. With the hash-based approach, you need to encode all of the relevant data int o a short string.

The replaceState() method

history.replaceState() operates exactly like history.pushState() except the replaceState() modifies the current history entry instead of creating a new one. Note that this doesn’t prevent the creation of a new entry in the global browser history.

replaceState() is particularly useful when you want to upate the state object or URL of the current history entry in reponse to some user action.

Example of replaceState() method

Suppose http://mozilla.org/foo.html executes the following JS:

1
2
var stateObj = { foo: 'bar' }
history.replaceState(stateObj, 'page 2', 'bar.htmk')

This will cause the URL bar to display http://mozilla.org/bar.html, but won’t cause the browser to load bar.html or even check that bar.html exists.

Suppose now that the user navigates to http://www.microsoft.com, then clicks back. At this point, the URL bar will display http://mozilla.org/bar.html.

If you click back again, you will be nagivated to the page before foo.html. (which is different from pushState())

The popstate event

A popstate event is dispatched to the window every time the active history entry changes. If the history entry being activated was created by a call to pushState or affected by replaceState, the popstate event’s state property contains a copy of the history entry’s state object.

Reading the current state

When your page loads, it might have a non-null state object. This can be happen, for example, if the page sets a state object(by pushState, or replaceState) and then the user restarts their browser. When your page reloads, the page will receive an onload event, but no popstate event. However if you read the history.state property, you’ll get back the state object you would have to gotten if a popstate had fired.

You can read it directly:

1
const currentState = history.state