Capítulo 189 de 456

useSearchParams

Core Idea

Client Component hook that reads the current URL's query string as a read-only URLSearchParams. In Server Components, prefer the page's searchParams prop instead.

Key Concepts

  • useSearchParams(): Sem parâmetros; retorna ReadonlyURLSearchParams (get, has, getAll, keys, values, entries, forEach, toString).
  • Prerendering: Chamar o hook faz o Client Component tree, até o Suspense mais próximo, ser client-side rendered.
  • Dynamic Rendering: Se a rota é dinâmica (ex. via connection()), o hook fica disponível já no render inicial do servidor.

Code Examples

'use client'
import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()
  const search = searchParams.get('search')
  // URL -> /dashboard?search=my-project => search = 'my-project'
  return <>Search: {search}</>
}

import { Suspense } from 'react'
import SearchBar from './search-bar'

function SearchBarFallback() { return <>placeholder</> }

export default function Page() {
  return (
    <>
      <nav><Suspense fallback={<SearchBarFallback />}><SearchBar /></Suspense></nav>
      <h1>Dashboard</h1>
    </>
  )
}
  • O que demonstra: Envolve o componente que usa useSearchParams num Suspense para deixar o resto da página prerenderizada como HTML estático inicial.

Reference Tables

URLsearchParams.get("a")
/dashboard?a=1'1'
/dashboard?a=''
/dashboard?b=3null
/dashboard?a=1&a=2'1' (use getAll())

Anti-patterns

  • Build estático sem Suspense boundary: falha com o erro "Missing Suspense boundary with useSearchParams".
  • Usar em Server Component: não é suportado, pode causar valores obsoletos durante partial rendering.

Key Takeaways

  1. Em produção, uma página estática que chama useSearchParams de um Client Component precisa de Suspense — em dev isso funciona sem erro (rotas renderizadas sob demanda), o que mascara o problema até o build.
  2. Se a intenção é renderização dinâmica, prefira connection() num Server Component antes, em vez do antigo export const dynamic = 'force-dynamic'.
  3. Layouts não recebem searchParams (evitaria re-render e ficaria stale); só Pages recebem o prop.
  4. Combine com useRouter/Link para escrever novos search params preservando os existentes.

Connects To

  • searchParams prop (page.js): alternativa em Server Components.
  • connection(): força renderização dinâmica de forma explícita.
  • useRouter: para atualizar search params programaticamente.
AnterioruseRouterPróximouseSelectedLayoutSegment