Function useSearchParams

Returns a tuple of the current URL's URLSearchParams and a function to update them. Setting the search params causes a navigation.

import { useSearchParams } from "react-router";

export function SomeComponent() {
  const [searchParams, setSearchParams] = useSearchParams();
  // ...
}
Copy

setSearchParams function

The second element of the tuple is a function that can be used to update the search params. It accepts the same types as defaultInit and will cause a navigation to the new URL.

let [searchParams, setSearchParams] = useSearchParams();

// a search param string
setSearchParams("?tab=1");

// a shorthand object
setSearchParams({ tab: "1" });

// object keys can be arrays for multiple values on the key
setSearchParams({ brand: ["nike", "reebok"] });

// an array of tuples
setSearchParams([["tab", "1"]]);

// a `URLSearchParams` object
setSearchParams(new URLSearchParams("?tab=1"));
Copy

It also supports a function callback like React's setState:

setSearchParams((searchParams) => {
  searchParams.set("tab", "2");
  return searchParams;
});
Copy

The function callback version of setSearchParams does not support the queueing logic that React's setState implements. Multiple calls to setSearchParams in the same tick will not build on the prior value. If you need this behavior, you can use setState manually.

Notes

Note that searchParams is a stable reference, so you can reliably use it as a dependency in React's useEffect hooks.

useEffect(() => {
  console.log(searchParams.get("tab"));
}, [searchParams]);
Copy

However, this also means it's mutable. If you change the object without calling setSearchParams, its values will change between renders if some other state causes the component to re-render and URL will not reflect the values.