Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Browser and Web APIs

The history object

Reference for window.history: go back and forward, add entries with pushState(), edit them with replaceState(), store state and handle popstate in single-page apps.

window.history gives your script access to the tab's session history, the list of pages the Back and Forward buttons move through. You can move through it with back(), forward() and go(), and, more powerfully, you can add or edit entries without loading a page using pushState() and replaceState().

The second ability is what lets single-page applications show clean URLs such as /profile/42 and still work with the Back button. Each entry can also carry a small state object that you read back later.

JavaScript
history.pushState({ id: 42 }, "", "/profile/42");  // new entry, no page load
history.replaceState({ id: 42, tab: "posts" }, ""); // edit the current entry
history.back();                                      // like the Back button

Try it

pushState and back() in action
JS What may be stored in state

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
history.length
history.state
history.scrollRestoration            // "auto" | "manual"

history.back()
history.forward()
history.go(delta)                    // go(-2), go(1), go(0) reloads

history.pushState(state, unused, url)
history.replaceState(state, unused, url)

Parameters of pushState() and replaceState()

Name Description
state Any structuredCloneable value (browsers limit its size, so keep it small), or null. Available later as history.state and event.state.
unused Ignored by browsers. Pass "".
url Optional. The new address, absolute or relative. It must have the same origin as the current page, otherwise a SecurityError is thrown.

Return value and errors

pushState(), replaceState(), back(), forward() and go() return undefined. pushState() and replaceState() throw SecurityError for a different origin (or a page where the call is not allowed) and DataCloneError for state that cannot be cloned.

Usage notes

  • Navigation by back() is asynchronous. The page changes later, and popstate fires then. Do not read location on the next line and expect the new value.
  • pushState() does not load anything and does not fire popstate. It only changes the URL bar and the history. Your code must render the new view itself.
  • Handle popstate. Going Back or Forward to an entry you created fires popstate with its state. Render the view for that entry.
  • replaceState() for refinements. Use it for things that should not add Back stops, such as updating a filter in the query string as the user types.
  • history.length counts the entries in the tab, but you cannot read the others for privacy reasons, and you cannot tell the current position.
  • The server must handle the URL. If you push /profile/42 and the user reloads, the server receives that path. Make it return your app for every route.
  • Scroll restoration. Set history.scrollRestoration = "manual" if you restore scroll positions yourself.
  • Browsers limit abuse. Calling pushState() or replaceState() very often in a short time can throw or be ignored in some browsers. Entries added without user interaction may be skipped by the Back button.
  • The Navigation API (window.navigation) is a newer, more complete alternative for single-page apps. It is not available in every browser yet, so check a compatibility table.

Browser support

The History API (back(), forward(), go(), pushState(), replaceState(), state) works in every current browser. scrollRestoration is supported broadly. The Navigation API is newer and not yet universal.