useRouter

Core Idea

Client Component hook for programmatic route changes (push, replace, refresh, prefetch, back, forward). Prefer <Link> for navigation and reserve useRouter for cases that need imperative control.

Key Concepts

• router.push(href, { scroll, transitionTypes }): Navega e adiciona entrada no histórico.
• router.replace(href, { scroll, transitionTypes }): Navega sem adicionar entrada no histórico.
• router.refresh(): Refaz o request ao servidor, re-fetch de dados e re-render de Server Components, sem perder estado client-side; limpa o Client Cache mas não invalida cache server-side (use revalidatePath/revalidateTag para isso).
• router.prefetch(href, { onInvalidate }): Prefetch manual; onInvalidate dispara quando o dado prefetchado fica stale.
• router.back() / router.forward(): Navega no histórico do browser.
• router.bfcacheId: Identificador opaco por segmento de rota; muda em push/replace fresco, mantém-se em back/forward, refresh e navegações só de search-param/hash.

Code Examples

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

export default function Page() {
  const router = useRouter()
  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

• O que demonstra: Navegação client-side imperativa via push, disparada por um handler de evento.

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

export default function Page() {
  const { bfcacheId } = useRouter()
  return <form key={bfcacheId}>{/* ... */}</form>
}

• O que demonstra: Usa bfcacheId como key do React para resetar estado em navegações novas mas preservá-lo em back/forward.

Anti-patterns

• Enviar URL não sanitizada para push/replace: abre risco de XSS (javascript: URLs são executadas no contexto da página).
• Usar bfcacheId como primeira opção: prefira resetar estado explicitamente num handler (onSubmit) ou derivar uma key dos próprios dados; bfcacheId é último recurso, ex. migração de código legado.

Key Takeaways

1. Importar de next/navigation, não next/router (mudança do Pages Router).
2. pathname e query do router antigo foram substituídos por usePathname() e useSearchParams().
3. <Link> já faz prefetch automático ao entrar no viewport; router.prefetch é para controle manual.
4. Com cacheComponents ativo, bfcacheId ajuda a preservar estado de Client Component via <Activity> em navegações back/forward.

Connects To

• usePathname / useSearchParams: substituem os campos removidos do router legado.
• revalidatePath / revalidateTag: necessários para invalidar cache server-side, que router.refresh() não faz.