History.replaceState()

The replaceState() method modifies the current history entry, replacing it with the state objects, title, 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.

Syntax

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

Parameters

state object

The state object is a JavaScript object which is associated with the history entry passed to the replaceState method. The state object can be null.

title

Most browsers currently ignores 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.

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.

Examples

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

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

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 http://mozilla.org/bar.html executes the following JavaScript:

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

This will cause the URL bar to display http://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 http://www.microsoft.com, then clicks the Back button. At this point, the URL bar will display http://mozilla.org/bar2.html. If the user now clicks Back again, the URL bar will display http://mozilla.org/foo.html, and totally bypass bar.html.

Specifications

Browser Compatibility