Query Strings (useSearchParams)

Reading URL parameters like ?page=2 or ?sort=asc.

Next.js5 min readConcept 40 of 65

Shareable State

useSearchParams is a Client Component hook that lets you read the query string of the current URL.

Storing state in the URL (like search filters or pagination) is a best practice because it allows users to bookmark and share exact views of your application.

The Read-Only API

The hook returns a read-only version of the standard URLSearchParams web API.

It provides utility methods like get('key'), getAll('key'), and has('key') to easily extract values without manually parsing strings.

Updating Parameters

useSearchParams only *reads* the parameters.

To update them, you must create a new URLSearchParams object, modify it, and pass it to useRouter().push(). There is no setSearchParams hook.

The Filter Flow

Click the color filters below to modify the URL. Watch how the mock hook reacts to the URL change, and note the Suspense Boundary warning.

Browser View

https://acme.com/shop
Ruby Sneakers
Sapphire Boots
Emerald Heels
Crimson Runners
Cobalt Loafers

Implementation

<Suspense>
export default function ProductList() {
const searchParams = useSearchParams();
const color = searchParams.get('color');
// color === null
return (
// Render products filtered by color...
);
}

Check yourself

Pick an answer to lock it in, then read why. Getting one wrong is part of how it sticks.

  1. 1What happens if you use `useSearchParams` without wrapping the component in a `<Suspense>` boundary?
  2. 2How do you update a search parameter using this hook?

Remember this

  • useSearchParams reads the query string (e.g., ?sort=asc).
  • It returns a READ-ONLY object. You cannot update the URL directly with it.
  • Using it forces dynamic rendering UNLESS you wrap the component in <Suspense>.
  • Server Components should use the searchParams prop instead of this hook.

Done with this concept?

Mark it complete to track your progress. No login needed.