useSearchParams

[MODES: framework, data, declarative]

Summary

Reference Documentation ↗

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();
  // ...
}

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"));

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

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

<docs-warning>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.</docs-warning>

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]);

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.

Signature

function useSearchParams(
  defaultInit?: URLSearchParamsInit,
): [URLSearchParams, SetURLSearchParams]

Params

defaultInit

You can initialize the search params with a default value, though it will not change the URL on the first render.

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

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

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

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

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

Returns

A tuple of the current URLSearchParams and a function to update them.