Client-side filtering
A list is already loaded through props and the browser query string controls local filtering.
Next.js 16+ · Hook
useSearchParams
useSearchParams is a Next.js Client Component hook for reading the current URL query string. It returns a read-only URLSearchParams interface and should be used inside Suspense for prerendered routes.
How it works
Call this Client Component hook to read the current URL query string. It returns a read-only URLSearchParams-like object, so use methods such as get, has, getAll, keys, values, or entries to inspect values. For rendering that depends on query parameters during prerendering, place the component below Suspense.
Syntax
const searchParams = useSearchParams()Returns
A read-only URLSearchParams interface.
Key points
- Import it from next/navigation to inspect query parameters from a Client Component.
- The hook is invoked without arguments.
- Use standard inspection methods such as get, getAll, has, keys, values, or entries.
- Put the hook-using component beneath Suspense when the route is statically rendered.
Common mistakes
- Do not call it from a Server Component; use the page searchParams prop there when server-side access is needed.
- A Suspense boundary is recommended when the route is prerendered, so surrounding Client Components can still be included in the initial HTML.
- Do not mutate the returned object; create a new URLSearchParams from its string representation when constructing updated query strings.
Example: Read a query parameter
'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchSummary() {
const searchParams = useSearchParams()
const query = searchParams.get('query') ?? 'all'
return <p>Filtering by: {query}</p>
}Reads the current query parameter in a Client Component.
When to use it
Interactive URL state
The current query value controls which tab, sort order, or view is displayed in an interactive component.
Navigation-aware UI
A Client Component needs to display or react to query values after navigation.
Interview questions
QWhat does useSearchParams return?
useSearchParams is a Client Component hook from next/navigation that reads the current URL query string. It returns a read-only URLSearchParams interface, so it can inspect values but is not an update API.
Follow-up: How would you update a query parameter? Create a new URLSearchParams from searchParams.toString(), change the copy, then navigate with the router or History API.
QCan useSearchParams run in a Server Component?
It cannot be used in a Server Component because the hook is intended for client-side rendering and navigation. A page should instead use its searchParams prop when the server needs query parameters.
Follow-up: When should the page prop be preferred? Use it when query parameters affect server-side data loading, such as database filtering or pagination.
QWhy is Suspense relevant when using the hook?
During prerendering, a component using the hook can suspend, so the documentation recommends placing it inside a Suspense boundary. This lets Client Components above the boundary remain prerenderable and be sent in the initial HTML.
Follow-up: What happens after client navigation? The router already has the URL parameters, allowing the hook to resolve synchronously during that navigation.
Related
URLSearchParamsusePathnameuseRoutersearchParamsSuspense