useSearchParams()

import { useSearchParams } from 'next/navigation'

const searchParams = useSearchParams()

useSearchParams gives a Client Component the query string as a read-only URLSearchParams. Use it for state you want to live in the URL — filters, sorting, pagination, a search box, the open tab — so the state is shareable, bookmarkable, and survives a reload. Writing is a separate step: build a new URLSearchParams from toString(), mutate the copy, and hand it to router.push or a <Link>.

The Suspense rule

This is the hook people file bugs about. On a prerendered route, calling it makes the whole Client Component tree up to the nearest <Suspense> boundary render on the client only. In development routes are rendered on demand, so it appears to work; the production build then fails outright. Wrap the component that calls the hook in <Suspense> with a fallback so everything above it can still be prerendered and streamed in the initial HTML.

What trips people up

• The object is read-only. searchParams.set(...) is not available; copy it first.
• On a Server Component page, prefer the searchParams prop of page.js — it is a Promise you await. Layouts never receive that prop, which is exactly when this hook is the right answer.
• get() returns only the first value for a repeated key; use getAll().
• If you want the route dynamic instead of client-rendered, await connection() in a parent Server Component rather than reaching for export const dynamic.

'use client'

import { useCallback } from 'react'
import { usePathname, useRouter, useSearchParams } from 'next/navigation'

export default function SortSelect() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // URL -> /products?sort=desc
  // sort -> 'desc'
  const sort = searchParams.get('sort') ?? 'asc'

  const setSort = useCallback(
    (value: string) => {
      // The returned object is read-only: copy it before mutating
      const params = new URLSearchParams(searchParams.toString())
      params.set('sort', value)
      router.push(`${pathname}?${params.toString()}`, { scroll: false })
    },
    [pathname, router, searchParams]
  )

  return (
    <select value={sort} onChange={(event) => setSort(event.target.value)}>
      <option value="asc">Price: low to high</option>
      <option value="desc">Price: high to low</option>
    </select>
  )
}

// app/products/page.tsx
import { Suspense } from 'react'
import SortSelect from './sort-select'

function SortSelectFallback() {
  return <select disabled aria-hidden />
}

export default function Page() {
  return (
    <>
      <h1>Products</h1>
      <Suspense fallback={<SortSelectFallback />}>
        <SortSelect />
      </Suspense>
      {/* the rest of the page is still prerendered */}
    </>
  )
}

// app/products/page.tsx — Server Component, Next.js 15+
export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const { sort = 'asc', q } = await searchParams

  const products = await getProducts({ sort, query: q })

  return <ProductList products={products} />
}

'use client'

import { useSearchParams } from 'next/navigation'

export default function ActiveFilters() {
  const searchParams = useSearchParams()

  // URL -> /shop?tag=new&tag=sale&min=10
  const tags = searchParams.getAll('tag') // ['new', 'sale']
  const first = searchParams.get('tag')   // 'new'
  const hasMin = searchParams.has('min')  // true

  return (
    <ul>
      {tags.map((tag) => (
        <li key={tag}>{tag}</li>
      ))}
      {hasMin ? <li>min {searchParams.get('min')}</li> : null}
    </ul>
  )
}