useSearchParams
API Reference for the useSearchParams hook.
useSearchParams
is a Client Component hook that lets you read the current URL's query string.
useSearchParams
returns a read-only version of the URLSearchParams
interface.
Parameters
useSearchParams
does not take any parameters.
Returns
useSearchParams
returns a read-only version of the URLSearchParams
interface, which includes utility methods for reading the URL's query string:
-
URLSearchParams.get()
: Returns the first value associated with the search parameter. For example:URL searchParams.get("a")
/dashboard?a=1
'1'
/dashboard?a=
''
/dashboard?b=3
null
/dashboard?a=1&a=2
'1'
- usegetAll()
to get all values -
URLSearchParams.has()
: Returns a boolean value indicating if the given parameter exists. For example:URL searchParams.has("a")
/dashboard?a=1
true
/dashboard?b=3
false
-
Learn more about other read-only methods of
URLSearchParams
, including thegetAll()
,keys()
,values()
,entries()
,forEach()
, andtoString()
.
Good to know:
useSearchParams
is a Client Component hook and is not supported in Server Components to prevent stale values during partial rendering.- If an application includes the
/pages
directory,useSearchParams
will returnReadonlyURLSearchParams | null
. Thenull
value is for compatibility during migration since search params cannot be known during pre-rendering of a page that doesn't usegetServerSideProps
Behavior
Static Rendering
If a route is statically rendered, calling useSearchParams
will cause the Client Component tree up to the closest Suspense
boundary to be client-side rendered.
This allows a part of the route to be statically rendered while the dynamic part that uses useSearchParams
is client-side rendered.
We recommend wrapping the Client Component that uses useSearchParams
in a <Suspense/>
boundary. This will allow any Client Components above it to be statically rendered and sent as part of initial HTML. Example.
For example:
Dynamic Rendering
If a route is dynamically rendered, useSearchParams
will be available on the server during the initial server render of the Client Component.
For example:
Good to know: Setting the dynamic
route segment config option to force-dynamic
can be used to force dynamic rendering.
Server Components
Pages
To access search params in Pages (Server Components), use the searchParams
prop.
Layouts
Unlike Pages, Layouts (Server Components) do not receive the searchParams
prop. This is because a shared layout is not re-rendered during navigation which could lead to stale searchParams
between navigations. View detailed explanation.
Instead, use the Page searchParams
prop or the useSearchParams
hook in a Client Component, which is re-rendered on the client with the latest searchParams
.
Examples
Updating searchParams
You can use useRouter
or Link
to set new searchParams
. After a navigation is performed, the current page.js
will receive an updated searchParams
prop.
Version History
Version | Changes |
---|---|
v13.0.0 | useSearchParams introduced. |