<Link>

<Link> ist eine React-Komponente, die das HTML-<a>-Element erweitert, um Prefetching und clientseitige Navigation zwischen Routen zu ermöglichen. Es ist die primäre Methode, um zwischen Routen in Next.js zu navigieren.

import Link from 'next/link'

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

import Link from 'next/link'

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

Props

Hier eine Übersicht der verfügbaren Props für die Link-Komponente:

Gut zu wissen: Attribute des <a>-Tags wie className oder target="_blank" können als Props an <Link> übergeben werden und werden an das zugrunde liegende <a>-Element weitergegeben.

href (erforderlich)

Der Pfad oder die URL, zu der navigiert werden soll.

<Link href="/dashboard">Dashboard</Link>

href kann auch ein Objekt akzeptieren, zum Beispiel:

// Navigiere zu /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  Über uns
</Link>

replace

Standardwert: false. Wenn true, ersetzt next/link den aktuellen Verlaufseintrag, anstatt eine neue URL zum Browserverlauf hinzuzufügen.

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

Standardwert: true. Das Standardverhalten von <Link> ist, nach einer Navigation zum Anfang der neuen Route zu scrollen oder die Scrollposition bei Vor- und Zurück-Navigation beizubehalten. Wenn false, scrollt next/link nach einer Navigation nicht zum Seitenanfang.

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

Gut zu wissen:

• Next.js scrollt zur Seite, wenn diese bei der Navigation nicht im Viewport sichtbar ist.

prefetch

Prefetching erfolgt, wenn eine <Link />-Komponente in den Viewport des Benutzers gelangt (initial oder durch Scrollen). Next.js lädt die verlinkte Route (angegeben durch href) und ihre Daten im Hintergrund, um die Leistung der clientseitigen Navigation zu verbessern. Prefetching ist nur in der Produktion aktiviert.

• null (Standard): Das Prefetch-Verhalten hängt davon ab, ob die Route statisch oder dynamisch ist. Für statische Routen wird die vollständige Route (inklusive aller Daten) prefetched. Für dynamische Routen wird der Teil der Route bis zum nächsten Segment mit einer loading.js-Grenze prefetched.
• true: Die vollständige Route wird für statische und dynamische Routen prefetched.
• false: Prefetching erfolgt weder beim Eintritt in den Viewport noch beim Hover.

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

Beispiele

Verlinkung zu dynamischen Routen

Für dynamische Routen kann es praktisch sein, Template-Literale zu verwenden, um den Pfad des Links zu erstellen.

Sie können beispielsweise eine Liste von Links zur dynamischen Route app/blog/[slug]/page.js generieren:

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

Wenn das Kind eine benutzerdefinierte Komponente ist, die ein <a>-Tag umschließt

Wenn das Kind von Link eine benutzerdefinierte Komponente ist, die ein <a>-Tag umschließt, müssen Sie passHref zu Link hinzufügen. Dies ist notwendig, wenn Sie Bibliotheken wie styled-components verwenden. Ohne dies hat das <a>-Tag kein href-Attribut, was die Barrierefreiheit Ihrer Seite beeinträchtigen und sich auf die SEO auswirken kann. Wenn Sie ESLint verwenden, gibt es eine integrierte Regel next/link-passhref, um die korrekte Verwendung von passHref sicherzustellen.

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

// Dies erstellt eine benutzerdefinierte Komponente, die ein <a>-Tag umschließt
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink

• Wenn Sie die JSX-Pragma-Funktion (@jsx jsx) von emotion verwenden, müssen Sie passHref verwenden, auch wenn Sie direkt ein <a>-Tag verwenden.
• Die Komponente sollte die onClick-Property unterstützen, um die Navigation korrekt auszulösen

Wenn das Kind eine Funktionskomponente ist

Wenn das Kind von Link eine Funktionskomponente ist, müssen Sie zusätzlich zu passHref und legacyBehavior die Komponente in React.forwardRef wrappen:

import Link from 'next/link'

// `onClick`, `href` und `ref` müssen an das DOM-Element übergeben werden
// für die korrekte Handhabung
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Klick mich
    </a>
  )
})

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

export default Home

Mit URL-Objekt

Link kann auch ein URL-Objekt erhalten und formatiert es automatisch, um die URL-Zeichenkette zu erstellen. Hier ist ein Beispiel:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          Über uns
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Blogbeitrag
        </Link>
      </li>
    </ul>
  )
}

export default Home

Das obige Beispiel enthält Links zu:

• Einer vordefinierten Route: /about?name=test
• Einer dynamischen Route: /blog/my-post

Sie können jede Property verwenden, wie in der Node.js URL-Modul-Dokumentation definiert.

URL ersetzen statt hinzufügen

Das Standardverhalten der Link-Komponente ist, eine neue URL zum history-Stack hinzuzufügen. Sie können die replace-Prop verwenden, um das Hinzufügen eines neuen Eintrags zu verhindern, wie im folgenden Beispiel:

<Link href="/about" replace>
  Über uns
</Link>

Scrollen zum Seitenanfang deaktivieren

Das Standardverhalten von Link ist, zum Seitenanfang zu scrollen. Wenn ein Hash definiert ist, wird zur spezifischen ID gescrollt, wie bei einem normalen <a>-Tag. Um das Scrollen zum Anfang/Hash zu verhindern, kann scroll={false} zu Link hinzugefügt werden:

<Link href="/#hashid" scroll={false}>
  Deaktiviert das Scrollen zum Anfang
</Link>

Middleware

Es ist üblich, Middleware für Authentifizierung oder andere Zwecke zu verwenden, die das Umleiten des Benutzers auf eine andere Seite beinhalten. Damit die <Link />-Komponente Links mit Rewrites über Middleware korrekt prefetchen kann, müssen Sie Next.js sowohl die anzuzeigende URL als auch die zu prefetchende URL mitteilen. Dies ist notwendig, um unnötige Abfragen an die Middleware zu vermeiden, um die korrekte Route zum Prefetchen zu ermitteln.

Wenn Sie beispielsweise eine /dashboard-Route bereitstellen möchten, die authentifizierte und Besucher-Ansichten hat, können Sie in Ihrer Middleware etwa Folgendes hinzufügen, um den Benutzer zur richtigen Seite umzuleiten:

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

In diesem Fall würden Sie folgenden Code in Ihrer <Link />-Komponente verwenden:

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

Versionsverlauf