history.replaceState() for Modifying Current Entry
You'll learn how to update the browser's current history entry without creating a new one in the navigation stack.
The Core Idea
While history.pushState() adds a new entry to the history stack (like adding a new page to a stack of papers), history.replaceState() modifies the current entry in place. Think of it like editing the top page instead of adding another one. The user can't go "back" to the previous state of the current page—you've simply updated what that state represents.
When to Use replaceState()
Use replaceState() when you want to:
- Update the URL to reflect changes within the same logical page
- Correct or refine the current state without adding to history
- Change URL parameters after initial page load without cluttering the back button
For example, if a user opens a modal dialog, you might want the URL to reflect that—but closing the modal shouldn't require hitting "back."
Syntax and Usage
history.replaceState(stateObject, unused, url);
The parameters work exactly like pushState():
stateObject: Data associated with this stateunused: Historical parameter (pass empty string or null)url: The new URL to display (optional)
// Update current entry to reflect filter state
history.replaceState(
{ filter: 'active', page: 1 },
'',
'?filter=active&page=1'
);
// Now the URL shows the filter, but no new history entry was created
ReplaceState vs PushState
The key difference: replaceState() doesn't change the history length. The user can't go back to what this entry was before you replaced it.
Key Takeaway: Use history.replaceState() to update the current history entry in place when you want to modify the URL or state without adding a new item to the navigation stack.