useLinkStatus

Core Idea

Track the pending state of a <Link> navigation to show subtle inline feedback (e.g. a shimmer) while navigation completes. Prefer route-level loading.js fallbacks and prefetching first; use this only as a targeted patch for a slow transition.

Key Concepts

• useLinkStatus(): Client hook returning { pending: boolean }; must be used within a descendant component of <Link>.
• pending: true before history updates, false after.
• prefetch={false}: The hook is most useful when disabled, since a prefetched route skips the pending phase entirely.

Code Examples

'use client'

import Link from 'next/link'
import { useLinkStatus } from 'next/link'

function Hint() {
  const { pending } = useLinkStatus()
  return <span aria-hidden className={`link-hint ${pending ? 'is-pending' : ''}`} />
}

export default function Header() {
  return (
    <header>
      <Link href="/dashboard" prefetch={false}>
        <span className="label">Dashboard</span> <Hint />
      </Link>
    </header>
  )
}

• O que demonstra: Hint fica dentro do <Link> e reage ao estado pendente sem alterar o layout do link em si.

Reference Tables

Property	Type	Description
pending	boolean	true before history updates, false after

Anti-patterns

• Indicador inline sem tamanho fixo: causa layout shift; prefira um elemento sempre renderizado, de tamanho fixo, alternando opacidade.
• Usar como primeira solução: navegação já é rápida por padrão; use useLinkStatus só depois de identificar uma transição lenta específica, e prefira corrigir a causa raiz com prefetch ou loading.js.

Key Takeaways

1. Só funciona dentro de um <Link> descendente; fora do Pages Router (que sempre retorna { pending: false }).
2. Se múltiplos links forem clicados rapidamente, só o pending state do último é mostrado.
3. Adicione animation-delay (~100ms) para evitar flash em navegações rápidas.
4. Não é o mecanismo padrão de loading — é um patch pontual.

Connects To

• Link Component: onde o hook deve estar aninhado.
• loading.js: fallback em nível de rota, preferível para a maioria dos casos.