Synchronize UI with query state
A filter, sort, or pagination control needs to reflect the current URL query without maintaining a duplicate source of truth.
Next.js 16+ · Class
ReadonlyURLSearchParams
ReadonlyURLSearchParams is the read-only query-string interface returned by Next.js useSearchParams. It lets Client Components inspect the current URL without directly mutating its search parameters.
How it works
ReadonlyURLSearchParams is the read-only URLSearchParams-like value returned by useSearchParams in a Client Component. It exposes methods for inspecting the current URL query string, while URL updates require creating a separate URLSearchParams instance.
Syntax
const searchParams = useSearchParams()Returns
A read-only URLSearchParams interface; in an application that includes the /pages directory, the result can be ReadonlyURLSearchParams | null.
Key points
- The value follows the familiar URLSearchParams interface but is exposed as read-only.
- Use its query-reading methods to inspect values already present in the browser URL.
- get(name) returns the first matching value when a query key occurs more than once.
- A project that still has a Pages Router directory may receive null for compatibility.
- Dynamic rendering can make the query value available during the initial server render of the Client Component.
Common mistakes
- Do not call useSearchParams in a Server Component; read the Page's searchParams prop there when server-side data access is needed.
- Projects containing a /pages directory must account for a possible null result during migration compatibility.
- The hook has no arguments; it reads the query string for the current URL.
Example: Read a query parameter
'use client'
import { useSearchParams } from 'next/navigation'
export default function FilterStatus() {
const searchParams = useSearchParams()
const status = searchParams.get('status')
return <p>Filter: {status ?? 'all'}</p>
}Reads the current URL's status query value in a Client Component.
When to use it
Read client-side URL filters
A Client Component displays a query value such as a search term, category, or status.
Handle repeated query keys
A component needs to distinguish the first value from all values for a repeated query key.
Interview questions
QWhat is ReadonlyURLSearchParams in Next.js?
It is the read-only version of the URLSearchParams interface returned by useSearchParams. It provides query-string reading utilities such as get, while preventing direct mutation of the current URL search parameters.
Follow-up: How would you update a query parameter? Create a new URLSearchParams from the read-only value, change the copy, and then update the URL through an appropriate client-side navigation mechanism.
QWhere is it used, and what is its purpose?
useSearchParams returns it in Client Components so they can inspect the current URL query string. The value is intended for reading, not for changing the URL directly.
Follow-up: Why is the hook unavailable in Server Components? The documentation says this prevents stale values during partial rendering; server-side query-dependent work should generally use the Page searchParams prop.
QHow do you read repeated query values?
The returned interface includes URLSearchParams reading methods, including get for the first value associated with a name. For repeated names, use getAll when all values are required.
Follow-up: What should a migrating Pages and App Router project type for the result? It should handle ReadonlyURLSearchParams | null because compatibility can produce null.
Related
useSearchParamsURLSearchParamssearchParams propusePathnameuseRouter