<Link>

<Link> est un composant React qui étend l'élément HTML <a> pour fournir le préchargement (prefetching) et la 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">Dashboard</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>
      Dashboard
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </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}>
      Dashboard
    </Link>
  )
}

import Link from 'next/link'

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

prefetch

Par défaut à true. Lorsque true, next/link préchargera la page (désignée par href) en arrière-plan. Ceci est utile pour améliorer les performances des navigations côté client. Tout <Link /> dans la zone visible (initialement ou via le défilement) sera préchargé.

Le préchargement peut être désactivé en passant prefetch={false}. Le préchargement n'est activé qu'en production.

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

Autres Props

legacyBehavior

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

Bon à savoir : lorsque legacyBehavior n'est pas défini sur true, toutes les propriétés de balise anchor peuvent également être transmises à next/link, telles que 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 modèle 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éfini 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 / 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 devriez 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' : '/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </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/[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