Composant <Link>

<Link> est un composant React qui étend l'élément HTML <a> pour fournir un préchargement et une navigation côté client entre les routes. C'est le moyen principal de naviguer entre les routes dans Next.js.

import Link from 'next/link'

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

import Link from 'next/link'

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

Props

Voici un résumé des props disponibles pour le composant Link :

Bon à savoir : Les attributs de balise <a> tels que className ou target="_blank" peuvent être ajoutés à <Link> comme props et seront transmis à l'élément <a> sous-jacent.

href (requis)

Le chemin ou l'URL vers lequel naviguer.

<Link href="/dashboard">Tableau de bord</Link>

href peut également accepter un objet, par exemple :

// Naviguer vers /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  À propos
</Link>

replace

Par défaut false. Lorsque true, next/link remplacera l'état actuel de l'historique au lieu d'ajouter une nouvelle URL dans la pile d'historique du navigateur.

import Link from 'next/link'

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

import Link from 'next/link'

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

scroll

Par défaut true. Le comportement par défaut de <Link> est de faire défiler vers le haut d'une nouvelle route ou de maintenir la position de défilement pour la navigation avant et arrière. Lorsque false, next/link ne fera pas défiler vers le haut de la page après une navigation.

import Link from 'next/link'

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

import Link from 'next/link'

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

Bon à savoir :

• Next.js fera défiler vers la Page si elle n'est pas visible dans la fenêtre d'affichage lors de la navigation.

prefetch

Le préchargement se produit lorsqu'un composant <Link /> entre dans la fenêtre d'affichage de l'utilisateur (initialement ou par défilement). Next.js précharge et charge la route liée (désignée par href) et ses données en arrière-plan pour améliorer les performances des navigations côté client. Le préchargement n'est activé qu'en production.

• null (par défaut) : Le comportement de préchargement dépend du fait que la route soit statique ou dynamique. Pour les routes statiques, la route complète sera préchargée (y compris toutes ses données). Pour les routes dynamiques, la route partielle jusqu'au segment le plus proche avec une limite loading.js sera préchargée.
• true : La route complète sera préchargée pour les routes statiques et dynamiques.
• false : Le préchargement ne se produira jamais, ni lors de l'entrée dans la fenêtre d'affichage, ni au survol.

import Link from 'next/link'

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

import Link from 'next/link'

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

Exemples

Lien vers des routes dynamiques

Pour les routes dynamiques, il peut être pratique d'utiliser des littéraux de gabarit pour créer le chemin du lien.

Par exemple, vous pouvez générer une liste de liens vers la route dynamique 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 l'enfant est un composant personnalisé qui encapsule une balise <a>

Si l'enfant de Link est un composant personnalisé qui encapsule une balise <a>, vous devez ajouter passHref à Link. Ceci est nécessaire si vous utilisez des bibliothèques comme styled-components. Sans cela, la balise <a> n'aura pas l'attribut href, ce qui nuit à l'accessibilité de votre site et peut affecter le SEO. Si vous utilisez ESLint, il existe une règle intégrée next/link-passhref pour garantir une utilisation correcte de passHref.

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

// Ceci crée un composant personnalisé qui encapsule une balise <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 vous utilisez la fonctionnalité JSX pragma d'emotion (@jsx jsx), vous devez utiliser passHref même si vous utilisez directement une balise <a>.
• Le composant doit prendre en charge la propriété onClick pour déclencher correctement la navigation.

Si l'enfant est un composant fonctionnel

Si l'enfant de Link est un composant fonctionnel, en plus d'utiliser passHref et legacyBehavior, vous devez encapsuler le composant dans React.forwardRef :

import Link from 'next/link'

// `onClick`, `href`, et `ref` doivent être transmis à l'élément DOM
// pour un traitement correct
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Cliquez ici
    </a>
  )
})

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

export default Home

Avec un objet URL

Link peut également recevoir un objet URL et le formatera automatiquement pour créer la chaîne d'URL. Voici comment faire :

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          À propos
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Article de blog
        </Link>
      </li>
    </ul>
  )
}

export default Home

L'exemple ci-dessus contient un lien vers :

• Une route prédéfinie : /about?name=test
• Une route dynamique : /blog/my-post

Vous pouvez utiliser chaque propriété comme définie dans la documentation du module URL de Node.js.

Remplacer l'URL au lieu de pousser

Le comportement par défaut du composant Link est de pousser une nouvelle URL dans la pile history. Vous pouvez utiliser la prop replace pour éviter d'ajouter une nouvelle entrée, comme dans l'exemple suivant :

<Link href="/about" replace>
  À propos
</Link>

Désactiver le défilement vers le haut de la page

Le comportement par défaut de Link est de faire défiler vers le haut de la page. Lorsqu'un hash est défini, il fera défiler vers l'id spécifique, comme une balise <a> normale. Pour empêcher le défilement vers le haut / le hash, scroll={false} peut être ajouté à Link :

<Link href="/#hashid" scroll={false}>
  Désactive le défilement vers le haut
</Link>

Middleware

Il est courant d'utiliser Middleware pour l'authentification ou d'autres fins impliquant la réécriture de l'utilisateur vers une page différente. Pour que le composant <Link /> précharge correctement les liens avec des réécritures via Middleware, vous devez indiquer à Next.js à la fois l'URL à afficher et l'URL à précharger. Ceci est nécessaire pour éviter des requêtes inutiles vers le middleware pour connaître la route correcte à précharger.

Par exemple, si vous souhaitez servir une route /dashboard qui a des vues authentifiées et visiteurs, vous pouvez ajouter quelque chose de similaire à ce qui suit dans votre Middleware pour rediriger l'utilisateur vers la page correcte :

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

Dans ce cas, vous voudriez utiliser le code suivant dans votre composant <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}>
      Tableau de bord
    </Link>
  )
}

Historique des versions