usePathname

Core Idea

Client Component hook that returns the current URL's pathname as a string. Reading the URL is intentionally not supported in Server Components, since that would break layout state preservation across navigations.

Key Concepts

• usePathname(): Sem parâmetros; retorna string do pathname (sem query string).
• Client-only: Não disponível em Server Components; o componente que o chama é baixado uma vez e re-renderiza no cliente conforme a navegação, sem novo fetch.

Code Examples

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

export default function ExampleClientComponent() {
  const pathname = usePathname()
  return <p>Current pathname: {pathname}</p>
}

• O que demonstra: Uso básico, sem parâmetros, retornando apenas o path (query string é excluída).

Reference Tables

URL	Returned value
/	'/'
/dashboard	'/dashboard'
/dashboard?v=2	'/dashboard'
/blog/hello-world	'/blog/hello-world'

Anti-patterns

• Ler usePathname() em página estaticamente prerenderizada com rewrites: pode causar hydration mismatch, pois o valor inicial vem do servidor (path de origem) e diverge do path reescrito no browser. Isole a leitura num componente pequeno que atualiza após o mount (useEffect).

Key Takeaways

1. Compatível com Pages Router quando ambos app e pages coexistem; o tipo de retorno se ajusta automaticamente.
2. Com cacheComponents ativo, rotas com params dinâmicos não cobertos por generateStaticParams fazem usePathname suspender; precisa de Suspense.
3. Combine com useSearchParams para reagir a qualquer mudança de rota via useEffect.
4. Para evitar mismatch de hidratação com rewrites, renderize um fallback estável no servidor e atualize a parte dependente do pathname após o mount.

Connects To

• useSearchParams: complementa lendo a query string.
• useRouter: para navegação programática combinada com leitura do pathname atual.