<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.

Para un ejemplo, considera 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 así:

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">Artículo del 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' },
  }}
>
  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 los datos en segundo plano para mejorar el rendimiento de las navegaciones del lado del cliente. El prefetching solo está habilitado en producción.

• true (predeterminado): Se precargará toda la ruta y sus datos.
• false: El prefetching no ocurrirá al entrar en el viewport, pero sí al pasar el cursor. Si deseas eliminar completamente el prefetching al pasar el cursor, considera usar una etiqueta <a> o adoptar incrementalmente el App Router, que permite deshabilitar el prefetching 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>
  )
}

Otras Props

legacyBehavior

Un elemento <a> ya no es necesario 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 también se pueden pasar 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 antepone 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 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>
  )
}

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/authed/[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