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.
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
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
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, andpopstatefires then. Do not readlocationon the next line and expect the new value. pushState()does not load anything and does not firepopstate. 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 firespopstatewith itsstate. 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.lengthcounts 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/42and 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()orreplaceState()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.