Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A query string parameter will not go away with useSearchParams

ErrorThe param is still in the URL after searchParams.delete()

Short answer

searchParams is a mutable object, but changing it does nothing to the URL. Only setSearchParams navigates. To remove one key, call delete on a copy inside the functional form of setSearchParams and return it. Do not call the setter twice in the same tick.

  • Applies to React 19, react-router 7
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find every place that touches the params. A delete without a setSearchParams call, or two setSearchParams calls in one handler, is the bug.

    grep -rn "searchParams\.\(delete\|set\)\|setSearchParams" src
  2. 2Match what you see, then jump to its fix

    1. 1The component shows the right value after a re-render, but the address bar does not change.searchParams.delete() was called without setSearchParamsFix
    2. 2You delete one param and set another in the same click handler; only the last change survives.Two setSearchParams calls in one handler overwrite each otherFix
    3. 3The URL has ?tag=a&tag=b and removing one tag removes both.You want to remove only one value of a repeated keyFix

What does the error look like?

  • The param is still in the URL after searchParams.delete()
  • Only one of two setSearchParams calls takes effect

Cause 1 of 3

searchParams.delete() was called without setSearchParams

1Check

The docs say searchParams is mutable. If you change it without calling setSearchParams, values may change between renders, but the URL will not reflect them.

grep -rn "searchParams.delete" src

2Fix

Make the change inside the functional form of the setter and return the object. URLSearchParams.delete removes every parameter with that name.

setSearchParams((prev) => {
  prev.delete("tab");
  return prev;
});

3Verify

The address bar loses ?tab= and the component re-renders without it.

console.log(window.location.search);

Confirmed by reactrouter.com

Did this fix it?

Cause 2 of 3

Two setSearchParams calls in one handler overwrite each other

1Check

The docs say the function form does not queue like React's setState: several calls in the same tick do not build on the prior value.

grep -rn -B2 -A6 "setSearchParams" src | head -60

2Fix

Do all changes in one updater call.

setSearchParams((prev) => {
  prev.delete("tab");
  prev.set("page", "1");
  return prev;
});

3Verify

After the click the URL has page=1 and no tab.

console.log(window.location.search);

Confirmed by reactrouter.com

Did this fix it?

Cause 3 of 3

You want to remove only one value of a repeated key

1Check

delete(name) removes every parameter with that name; the browser API also accepts a value as a second argument to remove only matching pairs.

new URLSearchParams('tag=a&tag=b').getAll('tag')

2Fix

Pass the value too.

setSearchParams((prev) => {
  prev.delete("tag", "a");
  return prev;
});

3Verify

Only tag=b remains.

console.log(new URLSearchParams(window.location.search).getAll('tag'));

Confirmed by developer.mozilla.org

Did this fix it?

How do I stop it coming back?

  • Treat searchParams as read-only outside the setter's callback.
  • Group every query change from one event into a single setSearchParams call.
  • Keep the param names in one small helper so delete and set use the same keys.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.