Web/API/History/replaceState

The History.replaceState() method modifies the current history entry, replacing it with the stateObj, 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, title, [url])

Parameters

stateObj: 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 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.
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 https://www.mozilla.org/foo.html executes the following JavaScript:

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

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

Specification	Status	Comment
HTML Living StandardThe definition of 'History.replaceState()' in that specification.	Living Standard	No change from HTML5.
HTML5The definition of 'History.replaceState()' in that specification.	Recommendation	Initial definition.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`replaceState`	Chrome Full support 5	Edge Full support 12	Firefox Full support 4 Notes' Full support 4 Notes' Notes' Until 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.	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 Notes' Full support 4 Notes' Notes' Until 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.	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.

History.replaceState() by Mozilla Contributors is licensed under CC-BY-SA 2.5.