In an HTML document, the history.pushState()
method adds a state to the browser's session history stack.
Syntax
history.pushState(state, title[, url])
Parameters
state
- 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, apopstate
event is fired, and thestate
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 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 usesessionStorage
and/orlocalStorage
. title
- Most browsers currently ignore this parameter, although they may use it in the future. Passing the empty string here should be safe against future changes to the method. Alternatively, you could pass a short title for the state to which you're moving.
url
Optional- 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 relative to the current URL. The new URL must be of the same origin as the current URL; otherwise,pushState()
will throw an exception. If this parameter isn't specified, it's set to the document's current URL.
Description
In a sense, calling pushState()
is similar to setting window.location = "#foo"
, in that both will also 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#foo
. - You can associate arbitrary data with your new history entry. With the hash-based approach, you need to encode all of the relevant data into a short string.
Note that pushState()
never causes a hashchange
event to be fired, even if the new URL differs from the old URL only in its hash.
Examples
This creates a new browser history state setting the state, title, and url.
JavaScript
const state = { 'page_id': 1, 'user_id': 5 } const title = '' const url = 'hello-world.html' history.pushState(state, title, url)
Specifications
Specification | Status | Comment |
---|---|---|
HTML Living Standard The definition of 'History.pushState()' in that specification. |
Living Standard | No change from HTML5. |
HTML5 The definition of 'History.pushState()' in that specification. |
Recommendation | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
pushState | Chrome Full support 5 | Edge Full support 12 | Firefox
Full support
4
| IE Full support 10 | Opera Full support 11.5 | Safari Full support 5 | WebView Android Full support ≤37 | Chrome Android Full support 18 | Firefox Android
Full support
4
| Opera Android Full support 11.5 | Safari iOS Full support 4.3 | Samsung Internet Android Full support 1.0 |
Whether the title argument is used | Chrome No support No | Edge No support No | Firefox No support No | IE No support No | Opera No support No | Safari Full support Yes | WebView Android No support No | Chrome Android No support No | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android No support No |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- See implementation notes.
- See implementation notes.