Capítulo 385 de 456

useSearchParams

Core Idea

Hook (de next/navigation, compartilhado entre Pages e App Router) que lê a query string atual da URL de forma read-only.

Key Concepts

  • useSearchParams(): sem parâmetros; retorna URLSearchParams read-only ou null durante prerendering
  • Comportamento no Pages Router: em páginas estaticamente otimizadas (sem getServerSideProps), retorna null até a hidratação
  • Comportamento com getServerSideProps: retorna os search params reais imediatamente (SSR por request)
  • Compartilhamento com App Router: mesmo hook funciona em pages/ e app/, permitindo componentes reutilizáveis

Code Examples

import { useSearchParams } from 'next/navigation'

export default function Dashboard() {
  const searchParams = useSearchParams()
  if (!searchParams) {
    return null // fallback durante prerender
  }
  const search = searchParams.get('search')
  return <>Search: {search}</>
}
  • O que demonstra: guarda contra null obrigatória antes de usar searchParams.get.
const createQueryString = useCallback(
  (name: string, value: string) => {
    const params = new URLSearchParams(searchParams?.toString())
    params.set(name, value)
    return params.toString()
  },
  [searchParams]
)
// router.push(router.pathname + '?' + createQueryString('sort', 'asc'))
  • O que demonstra: atualizar search params combinando useSearchParams (leitura) com useRouter.push (escrita).

Reference Tables

URLsearchParams.get("a")
/dashboard?a=1'1'
/dashboard?a=''
/dashboard?b=3null
/dashboard?a=1&a=2'1' (usar getAll() pra pegar todos os valores)
URLsearchParams.has("a")
/dashboard?a=1true
/dashboard?b=3false

Anti-patterns

  • Chamar .get() sem checar null primeiro: quebra em páginas estaticamente otimizadas durante prerender
  • Usar em class component: é um React Hook, não funciona fora de function component

Key Takeaways

  1. useSearchParams é sempre read-only; escrita de query params passa por router.push/replace
  2. null só ocorre em prerender de página estática do Pages Router, nunca com getServerSideProps
  3. É o hook certo para escrever componentes compartilháveis entre App Router e Pages Router (envolver em <Suspense> no App Router)

Connects To

  • useRouter (ch384): fornece a navegação para efetivamente mudar os search params lidos aqui
AnterioruseRouterPróximouserAgent