Capítulo 109 de 456

Link Component

Core Idea

<Link> (next/link) estende <a> para dar prefetching automático e navegação client-side entre rotas; é a forma primária de navegar entre rotas no Next.js.

Key Concepts

  • href (obrigatório): string ou objeto ({ pathname, query }).
  • replace: default false; quando true, substitui o history state em vez de empilhar nova entrada.
  • scroll: default true, mantém posição de scroll se a Page continuar visível, senão rola para o topo do primeiro elemento Page; elementos sticky/fixed são ignorados na busca pelo alvo de scroll.
  • prefetch: "auto"/null (default) prefetcha rota inteira se estática, ou parcial até o loading.js mais próximo se dinâmica; true prefetcha rota inteira sempre (com Partial Prefetching, inclui App Shell); false nunca prefetcha. Prefetch só ocorre em produção.
  • onNavigate: handler chamado durante navegação client-side, com preventDefault() disponível; diferente de onClick (que dispara em todo clique, inclusive Ctrl/Cmd+Click e downloads, onde onNavigate não dispara).
  • transitionTypes: lista passada a React.addTransitionType, para <ViewTransition> aplicar animações distintas por tipo de navegação.
  • Atributos <a> normais (className, target="_blank", etc.) passam direto para o elemento <a> subjacente.

Code Examples

import Link from 'next/link'

export default function Page() {
  return (
    <Link href={{ pathname: '/about', query: { name: 'test' } }}>
      About
    </Link>
  )
}
  • O que demonstra: href como objeto, navegando para /about?name=test.
'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function Links() {
  const pathname = usePathname()

  return (
    <nav>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>
    </nav>
  )
}
  • O que demonstra: link ativo detectado via usePathname() comparado ao href.
<Link href="/dashboard" prefetch={false}>
  Dashboard
</Link>
  • O que demonstra: desabilitar prefetch (nem ao entrar na viewport, nem no hover).

Reference Tables

PropExampleTypeRequired
hrefhref="/dashboard"String ou ObjectSim
replacereplace={false}Boolean-
scrollscroll={false}Boolean-
prefetchprefetch={false}Boolean ou null-
onNavigateonNavigate={(e) => {}}Function-
transitionTypestransitionTypes={['slide-in']}string[]-

Anti-patterns

  • Confundir onClick com onNavigate: onNavigate só roda em navegação client-side same-origin; não dispara com modifier keys (nova aba), URLs externas, ou atributo download.
  • Esperar scroll para elementos sticky/fixed: Next.js os ignora ao procurar o alvo de scroll, podendo esconder conteúdo atrás de header fixo, requer offset manual.
  • Usar <Link> para navegação para fora do site: prefetch e client-side navigation só funcionam same-origin; para link externo, target="_blank" funciona mas sem os benefícios de prefetch/onNavigate.

Key Takeaways

  1. Prefetch só acontece em produção, não em dev.
  2. scroll={false} também tem equivalente imperativo: router.push(url, { scroll: false }).
  3. href com hash (#id) funciona nativamente pois <Link> renderiza <a>.
  4. replace evita empilhar entrada no histórico, útil para navegação que não deve ser "voltada" (ex. após form submit).

Connects To

  • Components (ch105): índice dos componentes built-in.
  • Form Component (ch107): outra forma de navegação client-side com prefetch, orientada a formulários.
AnteriorImage ComponentPróximoScript Component