The pushState()
and replaceState()
methods add and modify history entries, respectively. These methods work in conjunction with the popstate
event.
The pushState()
and replaceState()
methods add and modify history entries, respectively. These methods work in conjunction with the popstate
event.
Using 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.
Suppose https://mozilla.org/foo.html
executes the following JavaScript:
js
const stateObj = { foo: "bar", }; history.pushState(stateObj, "page 2", "bar.html");
This will cause the URL bar to display https://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 https://google.com
, then clicks the Back button. At this point, the URL bar will display https://mozilla.org/bar.html
and history.state
will contain the stateObj
. The popstate
event won't be fired because the page has been reloaded. The page itself will look like bar.html
.
If the user clicks Back once again, the URL will change to https://mozilla.org/foo.html
, and the document will get a popstate
event, this time with a null
state object. Here too, going back doesn't change the document's contents from what they were in the previous step, although the document might update its contents manually upon receiving the popstate
event.
pushState()
takes three parameters: a state object; a title (currently ignored); and (optionally), a URL.
Let's examine each of these three parameters in more detail.
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.
Note: Some browsers save state objects to the user's disk so they can be restored after the user restarts the browser, and impose a size limit on the serialized representation of a state object, and will throw an exception if you pass a state object whose serialized representation is larger than that size limit. So in cases where you want to ensure you have more space than what some browsers might impose, you're encouraged to use sessionStorage
and/or localStorage
.
All browsers but Safari 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.
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. This 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 also create and activate another history entry associated with the current document.
But pushState()
has a few advantages:
window.location
keeps you at the same document
only if you modify only the hash.window.location = "#foo";
creates a new history entry only if the current hash isn't #foo
.title
is subsequently used by browsers, this data can be utilized (independent of, say, the hash).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.
In other documents, it creates an element with a null
namespace URI.
history.replaceState()
operates exactly like history.pushState()
, except that 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 update the state object or URL of the current history entry in response to some user action.
Suppose https://mozilla.org/foo.html
executes the following JavaScript:
js
const stateObj = { foo: "bar", }; history.pushState(stateObj, "page 2", "bar.html");
The explanation of these two lines above can be found at the above section Example of pushState() method section.
Next, suppose https://mozilla.org/bar.html
executes the following JavaScript:
js
history.replaceState(stateObj, "page 3", "bar2.html");
This will cause the URL bar to display https://mozilla.org/bar2.html
, but won't cause the browser to load bar2.html
or even check that bar2.html
exists.
Suppose now that the user navigates to https://www.microsoft.com
, then clicks the Back button. At this point, the URL bar will display https://mozilla.org/bar2.html
. If the user now clicks Back again, the URL bar will display https://mozilla.org/foo.html
, and totally bypass bar.html
.
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 a call to replaceState
, the popstate
event's state
property contains a copy of the history entry's state object.
See popstate
for sample usage.
When your page loads, it might have a non-null state object. This can happen, for example, if the page sets a state object (using pushState()
or replaceState()
) and then the user restarts their browser. When the 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 gotten if a popstate
had fired.
You can read the state of the current history entry without waiting for a popstate
event using the history.state
property like this:
js
const currentState = history.state;
history
global object
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/History_API/Working_with_the_History_API