Following #1807 — useSearchParams() now has delete/setAll/data, which covers the
read/write gap. But every mutator commits through the same helper:
const commit = (url: URL) => {
window.history.pushState({}, '', url)
sync()
}use-router.ts:181-184, used by set, delete, and setAll alike. There is no way to
replace the current entry instead of pushing a new one.
Why that blocks the common case
The canonical reason to delete a search param is to consume a one-shot value — an
OAuth callback result, a ?checkout=success, a flash token. The whole point is that it
must not survive a refresh or a Back press.
With pushState, deleting the param leaves the pre-delete URL — the one with the
param — as the previous history entry. Pressing Back replays the callback: the page
re-reads the param and re-runs whatever consuming it triggered (re-showing a success
toast at best, re-submitting at worst).
So the composable can express "remove this param from the URL" but not "remove this param so it's gone", which is the reason the API gets reached for.
Concrete case
Postline's accounts page consumes four OAuth provider callbacks. Each one reads its param, then strips it:
window.history.replaceState({}, '', `${route.path}${query ? `?${query}` : ''}`)I went to replace that with useSearchParams().delete(provider) as part of removing
vanilla window.* from views, and had to keep the raw call — swapping it in would
introduce the Back-replay bug above. That's the one remaining window.history use in
the app.
Suggested fix
An options bag on the mutators, defaulting to today's behaviour:
delete: (key: string, options?: { replace?: boolean }) => void
set: (key: string, value: string, options?: { replace?: boolean }) => void
setAll: (obj: Record<string, string>, options?: { replace?: boolean }) => voidwith commit choosing replaceState vs pushState accordingly. Non-breaking, and it
lines up with navigate(), which already takes { replace } after #1808 — right now
the two halves of the routing API disagree on whether replacing is expressible.
Docs point worth pairing with it: the current doc comments say "and push to history" on each mutator, which is accurate but reads as incidental. Whichever way it lands, it's worth stating that consuming a one-shot param needs replace semantics.