Use history.replaceState() when a same-document router needs to change the current URL without adding another entry to session history. Unlike history.pushState(), which adds an entry, replaceState() updates the current one. Choose it when Back should not return to the URL being corrected. section 10.3.6 section 11.2
Replace a temporary route after saving
After saving settings, navigate to /settings/saved with a replace option. The saved route takes the place of the temporary route rather than adding another stop for Back. The same choice works when removing ?page=1 or redirecting /login to /account after authentication. section 11.2
In a History API router, changing the URL is not the rendering step. replaceState() does not fire popstate, so call the route renderer after replacing the entry. Keep a popstate listener for later Back and Forward traversal. If the Navigation API is available, a navigation helper can instead use navigation.navigate() with history set to "replace" and let the normal navigation handler render. section 10.3.6 section 11.2
function goTo(url, { replace = false, state } = {}) {
const target = new URL(url, location.href);
if (target.origin !== location.origin) {
// External URL: hand off to the browser. The current document
// is about to be unloaded, so the returned promise will never
// resolve in this context. We return a resolved promise to keep
// the function's return type consistent for callers that don't
// await it.
location.href = target.href; #1
return Promise.resolve();
}
const routeUrl = target.pathname + target.search + target.hash;
if ("navigation" in globalThis) {
return navigation.navigate(routeUrl, { #2
history: replace ? "replace" : "push", #2
state #2
}).finished; #2
}
if (replace) { #3
history.replaceState(state ?? null, "", routeUrl); #3
} else { #3
history.pushState(state ?? null, "", routeUrl); #3
} #3
renderFromLocation(); #4
return Promise.resolve(); #5
}
The goTo() helper keeps the replace-or-push decision in one place. Its History API fallback calls history.replaceState(state ?? null, "", routeUrl) for replacement, then renders from the updated location; external URLs are handed to the browser. section 11.2
Keep native links as the baseline for navigation. A History API fallback must handle link clicks separately and leave external links, downloads, modifier-key clicks, and hash jumps to the browser. Replacing an entry does not supply those link behaviors or a unified navigation event. section 10.3.6
