history.replaceState
Modifies the current history entry, replacing it with the state, title, and URL passed in the method parameters
Syntax
history.replaceState(state, unused, url?)Parameters
| Parameter | Type | Description |
|---|---|---|
| state | any | A serializable object associated with the history entry |
| unused | string | This parameter exists for historical reasons |
| url | string | URL | The URL of the history entry |
Return Value
undefined
Examples
history.replaceState({ page: 'home' }, '', '/')
console.log(history.state) // { page: 'home' }function updateQueryString(params: Record<string, string>) {
const url = new URL(window.location.href)
Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v))
history.replaceState(null, '', url)
}function setLocale(locale: string) {
const url = new URL(window.location.href)
url.searchParams.set('lang', locale)
history.replaceState({ locale }, '', url)
}Understanding history.replaceState
The history.replaceState method in JavaScript modifies the current history entry, replacing it with the state, title, and URL passed in the method parameters. It belongs to the History object and is one of the most widely used methods for working with history values in modern JavaScript and TypeScript applications.
The method signature is history.replaceState(state, unused, url?). It accepts 3 parameters: state, unused, url. When called, it returns undefined. Understanding when and how to use replaceState() helps you write more expressive, readable code.
Common use cases for history.replaceState include data transformation, input validation, API response processing, and building reusable utility functions. It works well alongside related methods like history-pushstate, history-back, history-go, enabling you to chain operations together for complex data manipulation pipelines.
Browser support for history.replaceState is excellent across all modern browsers including Chrome, Firefox, Safari, and Edge. It is also fully supported in Node.js and Deno. For older environments, transpilation with Babel or a polyfill may be needed.
Browser Compatibility
Supported in all modern browsers (Chrome, Firefox, Safari, Edge) and Node.js. Part of the ECMAScript standard.
Related Methods
history.pushStatePushes the given data onto the session history stack with the specified title and, if provided, URL
history.backCauses the browser to move back one page in the session history, equivalent to clicking the browser's back button
history.goLoads a page from the session history, identified by its relative location to the current page
More History Methods
Other methods in the History object
Related Tools
More History Methods
Explore JavaScript Methods
Browse our complete reference of 410 JavaScript methods with syntax, examples, and explanations.