useParams

Core Idea

Client Component hook to read a route's filled-in dynamic params from the current URL, when you don't have direct access to the params prop (e.g. deep in a shared component).

Key Concepts

• useParams(): Sem parâmetros; retorna objeto com os segmentos dinâmicos ativos.
• Valor de cada propriedade: string ou string[] dependendo se o segmento é [slug] ou [...slug].

Code Examples

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

export default function ExampleClientComponent() {
  const params = useParams<{ tag: string; item: string }>()
  // Route -> /shop/[tag]/[item]
  // URL -> /shop/shoes/nike-air-max-97
  // params -> { tag: 'shoes', item: 'nike-air-max-97' }
  return '...'
}

• O que demonstra: Tipagem genérica opcional em TS e o shape do objeto retornado para uma rota com dois segmentos dinâmicos.

Reference Tables

Route	URL	useParams()
app/shop/page.js	/shop	{}
app/shop/[slug]/page.js	/shop/1	{ slug: '1' }
app/shop/[tag]/[item]/page.js	/shop/1/2	{ tag: '1', item: '2' }
app/shop/[...slug]/page.js	/shop/1/2	{ slug: ['1', '2'] }

Anti-patterns

• Chamar sem Suspense em rota com params não cobertos por generateStaticParams: com cacheComponents ativo, useParams suspende; o build falha sem boundary de Suspense.

Key Takeaways

1. Rotas estáticas ou cobertas por generateStaticParams resolvem no servidor sem precisar de Suspense.
2. Rotas com params dinâmicos desconhecidos até o request precisam de Suspense ao redor do componente (ou de um pai).
3. No Pages Router retorna null até o router estar pronto.

Connects To

• generateStaticParams: determina se os params são conhecidos em build time (afeta necessidade de Suspense).
• dynamic-routes: convenção de arquivos que define os segmentos que useParams lê.