In a client-side router, when should you call history.replaceState() instead of history.pushState(), and what goes wrong if you always push?

## The one difference Both calls take the same arguments — `(state, unused, url)` — and both are silent, firing no `popstate` or `hashchange`. The distinction is what happens to the session history entry list: - `pushState` **inserts** a new entry after the current one, discards any forward entries, and makes the new entry current. `history.length` grows by one. - `replaceState` **overwrites** the current entry's URL and state. The list length and position are unchanged, and forward entries are preserved. Everything else follows from that. Push makes the previous view reachable by Back; replace makes it as if the current view had always had this URL. ## When replace is the right call **High-frequency URL syncing.** A search field, a price slider, a sortable table — anything that writes its state into the query string as the user manipulates it. Each keystroke is not a navigation. Push once when the user *enters* the filtered view, then replace as the parameters change. ```js let timer; input.addEventListener('input', () => { clearTimeout(timer); timer = setTimeout(() => { const url = new URL(location.href); url.searchParams.set('q', input.value); history.replaceState(history.state, '', url); // no new entry }, 200); }); ``` Note the debounce: even `replaceState` should not run on every keypress, because some browsers throttle rapid history mutations, and rewriting the URL sixty times a second is wasted work. **Redirects.** If /old-path forwards to /new-path, or /login forwards to /dashboard after a successful sign-in, push would leave the intermediate URL on the stack, and Back would bounce the user straight back into the redirect — a loop they cannot escape. Replace removes the intermediate step from history entirely. **Canonicalization.** The user pasted `/Products?ref=email&utm_source=x`. Rewriting it to `/products` with `replaceState` cleans the address bar and future bookmarks without adding a step. **Seeding state on load.** The initial entry created by a normal page load has `history.state === null`. A router that wants every entry to carry state calls `replaceState({ key: crypto.randomUUID() }, '', location.href)` at boot so the first entry is not the odd one out. ## The cost of over-pushing History is a shared resource owned by the user, not by your app. Over-pushing produces a **history trap**: the user opened your app from a search result, changed a few filters, and now needs eight presses of Back to get out. On Android the hardware back gesture is the same stack, so the app appears to refuse to close. Analytics also degrades, because every pseudo-navigation looks like a page view. There is no way to repair it after the fact. The History API exposes no method to delete entries, enumerate them, or truncate the stack; `history.length` is read-only, and `history.go(-n)` merely traverses. Chrome ships a history-manipulation intervention that skips over entries created by a page the user never interacted with, which softens the worst abuse, but you cannot rely on it. The only real control is deciding push versus replace at the moment of the change. ## What history.length actually counts `history.length` is the number of entries in the **whole tab's** session history, not your app's. A tab that visited two other sites before yours starts at 3. It never decreases from replaces, and it is capped by the browser. Because you cannot see the entries or their URLs — that would leak browsing history across origins — code such as `if (history.length > 1) history.back()` is unreliable: the previous entry may belong to another site, and you have just sent the user off your app. A router that needs a trustworthy "is there somewhere to go back to inside this app" answer must track its own depth in the state it pushes. ## A useful rule of thumb Ask: *if the user pressed Back right now, what would they expect to see?* If the answer is "the thing before this change", push. If the answer is "the thing before I arrived at this screen at all", replace. Getting that question right for each state change is the whole of the design.