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

Pour un exemple, considérez un répertoire pages avec les fichiers suivants :

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

Nous pouvons avoir un lien vers chacune de ces pages comme suit :

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/">Accueil</Link>
      </li>
      <li>
        <Link href="/about">À propos</Link>
      </li>
      <li>
        <Link href="/blog/hello-world">Article de blog</Link>
      </li>
    </ul>
  )
}

export default Home

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

• true (par défaut) : La route complète et ses données seront préchargées.
• false : Le préchargement ne se produira pas lors de l'entrée dans la fenêtre d'affichage, mais se produira au survol. Si vous souhaitez également supprimer le préchargement au survol, envisagez d'utiliser une balise <a> ou d'adopter progressivement le routeur App, qui permet également de désactiver le préchargement 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>
  )
}

Autres Props

legacyBehavior

Une balise <a> n'est plus requise comme enfant de <Link>. Ajoutez la prop legacyBehavior pour utiliser le comportement hérité ou supprimez la balise <a> pour mettre à niveau. Un codemod est disponible pour mettre à niveau automatiquement votre code.

Bon à savoir : lorsque legacyBehavior n'est pas défini sur true, toutes les propriétés de la balise anchor peuvent également être transmises à next/link, comme className, onClick, etc.

passHref

Force Link à transmettre la propriété href à son enfant. Par défaut false.

scroll

Fait défiler vers le haut de la page après une navigation. Par défaut true.

shallow

Met à jour le chemin de la page actuelle sans réexécuter getStaticProps, getServerSideProps ou getInitialProps. Par défaut false.

locale

La locale active est automatiquement préfixée. locale permet de fournir une locale différente. Lorsque false, href doit inclure la locale car le comportement par défaut est désactivé.

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

Bon à savoir : Si vous utilisez des Routes dynamiques, vous devrez adapter vos props as et href. Par exemple, si vous avez une Route dynamique comme /dashboard/authed/[user] que vous souhaitez présenter différemment via middleware, vous écrirez : <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profil</Link>.

Historique des versions