W3cubDocs

/Web APIs

History: replaceState() method

The History.replaceState() method modifies the current history entry, replacing it with the state object and URL passed in the method parameters. This method is particularly useful when you want to update the state object or URL of the current history entry in response to some user action.

This method is asynchronous. Add a listener for the popstate event in order to determine when the navigation has completed. The state parameter will be available in it.

Syntax

js

replaceState(state, unused)
replaceState(state, unused, url)

Parameters

state

An object which is associated with the history entry passed to the replaceState() method. The state object can be null.

unused

This parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional, and safe against future changes to the method.

url Optional

The URL of the history entry. The new URL must be of the same origin as the current URL; otherwise replaceState throws an exception.

Return value

None (undefined).

Examples

Suppose https://www.mozilla.org/foo.html executes the following JavaScript:

js

const stateObj = { foo: "bar" };
history.pushState(stateObj, "", "bar.html");

On the next page you could then use history.state to access the stateObj that was just added.

The explanation of these two lines above can be found in the Example of pushState() method section of the Working with the History API article. Then suppose https://www.mozilla.org/bar.html executes the following JavaScript:

js

history.replaceState(stateObj, "", "bar2.html");

This will cause the URL bar to display https://www.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://www.mozilla.org/bar2.html. If the user now clicks Back again, the URL bar will display https://www.mozilla.org/foo.html, and totally bypass bar.html.

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
replaceState 5 12
4Until Firefox 5, the passed object is serialized using JSON. Starting in Firefox 6, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
10 11.5 5 ≤37 18
4Until Firefox 5, the passed object is serialized using JSON. Starting in Firefox 6, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
11.5 4 1.0
unused_parameter No No No No No
5This feature may be removed, see bug 223190.
No No No No
4This feature may be removed, see bug 223190.
No

© 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/replaceState