<Link>

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

Para un ejemplo, considere un directorio pages con los siguientes archivos:

• pages/index.js
• pages/about.js
• pages/blog/[slug].js

Podemos tener un enlace a cada una de estas páginas de la siguiente manera:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/">Inicio</Link>
      </li>
      <li>
        <Link href="/about">Sobre Nosotros</Link>
      </li>
      <li>
        <Link href="/blog/hello-world">Entrada de Blog</Link>
      </li>
    </ul>
  )
}

export default Home

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' },
  }}
>
  Sobre Nosotros
</Link>

replace

Por defecto es 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 es 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>
  )
}

prefetch

Por defecto es true. Cuando es true, next/link precargará la página (denotada por href) en segundo plano. Esto es útil para mejorar el rendimiento de las navegaciones del lado del cliente. Cualquier <Link /> en el viewport (inicialmente o mediante desplazamiento) será precargado.

La precarga puede desactivarse pasando prefetch={false}. La precarga solo está habilitada en producción.

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>
  )
}

Otras Props

legacyBehavior

Un elemento <a> ya no es requerido como hijo de <Link>. Agrega la prop legacyBehavior para usar el comportamiento heredado o elimina el <a> para actualizar. Hay un codemod disponible para actualizar automáticamente tu código.

Bueno saber: cuando legacyBehavior no está establecido en true, todas las propiedades de la etiqueta anchor pueden pasarse a next/link, como className, onClick, etc.

passHref

Fuerza a Link a enviar la propiedad href a su hijo. Por defecto es false.

scroll

Desplazarse a la parte superior de la página después de una navegación. Por defecto es true.

shallow

Actualiza la ruta de la página actual sin volver a ejecutar getStaticProps, getServerSideProps o getInitialProps. Por defecto es false.

locale

La configuración regional activa se agrega automáticamente. locale permite proporcionar una configuración regional diferente. Cuando es false, href debe incluir la configuración regional ya que el comportamiento predeterminado está deshabilitado.

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 pages/blog/[slug].js:

import Link from 'next/link'

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

export default Posts

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 soportar 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' },
          }}
        >
          Entrada de 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>

Desactivar 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}>
  Desactiva el desplazamiento a la parte superior
</Link>

Middleware

Es común usar Middleware para autenticación u otros propósitos que involucren 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 para mostrar como la URL para precargar. Esto es necesario para evitar solicitudes innecesarias al middleware para conocer la ruta correcta a 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' : '/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

Bueno saber: Si estás usando Rutas Dinámicas, necesitarás adaptar tus props as y href. Por ejemplo, si tienes una Ruta Dinámica como /dashboard/[user] que deseas presentar de manera diferente a través de middleware, escribirías: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Perfil</Link>.

Historial de Versiones