Componente <Link>

<Link> es un componente de React que extiende el elemento HTML <a> para proporcionar prefetching y navegación del lado del cliente entre rutas. Es la forma principal de navegar entre rutas en Next.js.

import Link from 'next/link'

export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

import Link from 'next/link'

export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

Props

Aquí hay un resumen de las props disponibles para el componente Link:

Bueno saber: Los atributos de la etiqueta <a> como className o target="_blank" pueden agregarse a <Link> como props y se pasarán al elemento <a> subyacente.

href (requerido)

La ruta o URL a la que navegar.

<Link href="/dashboard">Dashboard</Link>

href también puede aceptar un objeto, por ejemplo:

// Navegar a /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  Acerca de
</Link>

replace

Por defecto false. Cuando es true, next/link reemplazará el estado actual del historial en lugar de agregar una nueva URL a la pila del historial del navegador.

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

scroll

Por defecto true. El comportamiento predeterminado de <Link> es desplazarse a la parte superior de una nueva ruta o mantener la posición de desplazamiento para navegación hacia atrás y adelante. Cuando es false, next/link no se desplazará a la parte superior de la página después de una navegación.

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      Dashboard
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      Dashboard
    </Link>
  )
}

Bueno saber:

• Next.js se desplazará a la Página si no está visible en el viewport al navegar.

prefetch

El prefetching ocurre cuando un componente <Link /> entra en el viewport del usuario (inicialmente o mediante desplazamiento). Next.js precarga y carga la ruta vinculada (denotada por href) y sus datos en segundo plano para mejorar el rendimiento de las navegaciones del lado del cliente. El prefetching solo está habilitado en producción.

• null (predeterminado): El comportamiento de prefetch depende de si la ruta es estática o dinámica. Para rutas estáticas, se precargará toda la ruta (incluidos todos sus datos). Para rutas dinámicas, se precargará la ruta parcial hasta el segmento más cercano con un límite loading.js.
• true: Se precargará toda la ruta tanto para rutas estáticas como dinámicas.
• false: El prefetching nunca ocurrirá al entrar en el viewport ni al pasar el cursor.

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

Ejemplos

Enlaces a Rutas Dinámicas

Para rutas dinámicas, puede ser útil usar literales de plantilla para crear la ruta del enlace.

Por ejemplo, puedes generar una lista de enlaces a la ruta dinámica app/blog/[slug]/page.js:

import Link from 'next/link'

function Page({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

Si el hijo es un componente personalizado que envuelve una etiqueta <a>

Si el hijo de Link es un componente personalizado que envuelve una etiqueta <a>, debes agregar passHref a Link. Esto es necesario si estás usando bibliotecas como styled-components. Sin esto, la etiqueta <a> no tendrá el atributo href, lo que perjudica la accesibilidad de tu sitio y podría afectar el SEO. Si estás usando ESLint, hay una regla incorporada next/link-passhref para garantizar el uso correcto de passHref.

import Link from 'next/link'
import styled from 'styled-components'

// Esto crea un componente personalizado que envuelve una etiqueta <a>
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink

• Si estás usando la función JSX pragma de emotion (@jsx jsx), debes usar passHref incluso si usas una etiqueta <a> directamente.
• El componente debe admitir la propiedad onClick para activar la navegación correctamente.

Si el hijo es un componente funcional

Si el hijo de Link es un componente funcional, además de usar passHref y legacyBehavior, debes envolver el componente en React.forwardRef:

import Link from 'next/link'

// `onClick`, `href` y `ref` deben pasarse al elemento DOM
// para un manejo adecuado
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Haz clic aquí
    </a>
  )
})

function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}

export default Home

Con Objeto URL

Link también puede recibir un objeto URL y lo formateará automáticamente para crear la cadena de URL. Así es cómo hacerlo:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          Sobre nosotros
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Artículo del Blog
        </Link>
      </li>
    </ul>
  )
}

export default Home

El ejemplo anterior tiene un enlace a:

• Una ruta predefinida: /about?name=test
• Una ruta dinámica: /blog/my-post

Puedes usar cada propiedad como se define en la documentación del módulo URL de Node.js.

Reemplazar la URL en lugar de empujar

El comportamiento predeterminado del componente Link es empujar una nueva URL a la pila del historial. Puedes usar la prop replace para evitar agregar una nueva entrada, como en el siguiente ejemplo:

<Link href="/about" replace>
  Sobre nosotros
</Link>

Deshabilitar el desplazamiento a la parte superior de la página

El comportamiento predeterminado de Link es desplazarse a la parte superior de la página. Cuando hay un hash definido, se desplazará al id específico, como una etiqueta <a> normal. Para evitar el desplazamiento a la parte superior / hash, se puede agregar scroll={false} a Link:

<Link href="/#hashid" scroll={false}>
  Deshabilita el desplazamiento a la parte superior
</Link>

Middleware

Es común usar Middleware para autenticación u otros propósitos que implican reescribir al usuario a una página diferente. Para que el componente <Link /> precargue correctamente los enlaces con reescrituras a través de Middleware, debes indicarle a Next.js tanto la URL que se mostrará como la URL que se precargará. Esto es necesario para evitar solicitudes innecesarias al middleware para conocer la ruta correcta que se debe precargar.

Por ejemplo, si deseas servir una ruta /dashboard que tenga vistas autenticadas y de visitante, puedes agregar algo similar a lo siguiente en tu Middleware para redirigir al usuario a la página correcta:

export function middleware(req) {
  const nextUrl = req.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (req.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', req.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', req.url))
    }
  }
}

En este caso, querrías usar el siguiente código en tu componente <Link />:

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed'

export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

Historial de versiones