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.

Grundlegende Verwendung:

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

Referenz

Die folgenden Props können an die <Link>-Komponente übergeben werden:

Prop	Beispiel	Typ	Erforderlich
`href`	`href="/dashboard"`	String oder Objekt	Ja
`replace`	`replace={false}`	Boolean	-
`scroll`	`scroll={false}`	Boolean	-
`prefetch`	`prefetch={false}`	Boolean oder null	-
`onNavigate`	`onNavigate={(e) => {}}`	Funktion	-

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.

import Link from 'next/link'

// Navigiere zu /about?name=test
export default function Page() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      About
    </Link>
  )
}

import Link from 'next/link'

// Navigiere zu /about?name=test
export default function Page() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      About
    </Link>
  )
}

`replace`

Standardwert ist false. Wenn true, ersetzt next/link den aktuellen Verlaufseintrag, anstatt eine neue URL in den Browserverlauf einzufü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 ist true. Das Standard-Scrollverhalten von <Link> in Next.js ist die Beibehaltung der Scrollposition, ähnlich wie Browser das Zurück- und Vorwärtsnavigieren handhaben. Wenn Sie zu einer neuen Page navigieren, bleibt die Scrollposition erhalten, solange die Page im Viewport sichtbar ist. Falls die Page nicht im Viewport sichtbar ist, scrollt Next.js zum obersten Element der Page.

Wenn scroll = {false}, versucht Next.js nicht, zum ersten Page-Element zu scrollen.

Gut zu wissen: Next.js prüft scroll: false, bevor es das Scrollverhalten steuert. Wenn das Scrollen aktiviert ist, identifiziert es das relevante DOM-Element für die Navigation und überprüft jedes Top-Level-Element. Alle nicht scrollbaren Elemente und solche ohne gerendertes HTML werden übersprungen, einschließlich Elementen mit fester oder klebender Positionierung und nicht sichtbaren Elementen, die mit getBoundingClientRect berechnet wurden. Next.js durchläuft dann die Geschwisterelemente, bis es ein scrollbares Element findet, das im Viewport sichtbar ist.

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`

Das 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. Wenn die geprefetchten Daten abgelaufen sind, wenn der Benutzer über einen <Link /> hovered, versucht Next.js, sie erneut zu prefetchen. Prefetching ist nur in der Produktion aktiviert.

Folgende Werte können an die prefetch-Prop übergeben werden:

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) geprefetched. Für dynamische Routen wird die partielle Route bis zum nächsten Segment mit einer loading.js-Grenze geprefetched.
true: Die vollständige Route wird für statische und dynamische Routen geprefetched.
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>
  )
}

`onNavigate`

Ein Event-Handler, der während der clientseitigen Navigation aufgerufen wird. Der Handler erhält ein Event-Objekt, das eine preventDefault()-Methode enthält, mit der Sie die Navigation bei Bedarf abbrechen können.

import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // Wird nur während der SPA-Navigation ausgeführt
        console.log('Navigating...')

        // Optional Navigation abbrechen
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // Wird nur während der SPA-Navigation ausgeführt
        console.log('Navigating...')

        // Optional Navigation abbrechen
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

Gut zu wissen: Obwohl onClick und onNavigate ähnlich erscheinen, dienen sie unterschiedlichen Zwecken. onClick wird für alle Klick-Events ausgeführt, während onNavigate nur während der clientseitigen Navigation läuft. Einige wichtige Unterschiede:

Bei Verwendung von Modifizierertasten (Strg/Cmd + Klick) wird onClick ausgeführt, aber onNavigate nicht, da Next.js die Standardnavigation für neue Tabs verhindert.

Externe URLs lösen onNavigate nicht aus, da es nur für clientseitige und same-origin-Navigationen gilt.

Links mit dem download-Attribut funktionieren mit onClick, aber nicht mit onNavigate, da der Browser die verlinkte URL als Download behandelt.

Beispiele

Die folgenden Beispiele zeigen, wie die <Link>-Komponente in verschiedenen Szenarien verwendet wird.

Verlinkung zu dynamischen Segmenten

Beim Verlinken zu dynamischen Segmenten können Sie Template-Literale und Interpolation verwenden, um eine Liste von Links zu generieren. Zum Beispiel, um eine Liste von Blogposts zu generieren:

import Link from 'next/link'

interface Post {
  id: number
  title: string
  slug: string
}

export default function PostList({ posts }: { posts: Post[] }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

import Link from 'next/link'

export default function PostList({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

Aktive Links überprüfen

Sie können usePathname() verwenden, um festzustellen, ob ein Link aktiv ist. Um beispielsweise eine Klasse zum aktiven Link hinzuzufügen, können Sie prüfen, ob der aktuelle pathname mit dem href des Links übereinstimmt:

'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function Links() {
  const pathname = usePathname()

  return (
    <nav>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>

      <Link
        className={`link ${pathname === '/about' ? 'active' : ''}`}
        href="/about"
      >
        About
      </Link>
    </nav>
  )
}

'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function Links() {
  const pathname = usePathname()

  return (
    <nav>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>

      <Link
        className={`link ${pathname === '/about' ? 'active' : ''}`}
        href="/about"
      >
        About
      </Link>
    </nav>
  )
}

Zu einer `id` scrollen

Wenn Sie zu einer bestimmten id navigieren möchten, können Sie Ihre URL mit einem #-Hash-Link ergänzen oder einfach einen Hash-Link an die href-Prop übergeben. Dies ist möglich, da <Link> in ein <a>-Element gerendert wird.

<Link href="/dashboard#settings">Settings</Link>

// Ausgabe
<a href="/dashboard#settings">Settings</a>

Gut zu wissen:

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

Verlinkung zu dynamischen Routensegmenten

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

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

import Link from 'next/link'

export default function Page({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

import Link from 'next/link'

export default 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 Website beeinträchtigt und sich möglicherweise auf die SEO auswirkt. 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

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 auch dann verwenden, wenn Sie direkt ein <a>-Tag verwenden.
Die Komponente sollte die onClick-Property unterstützen, um die Navigation korrekt auszulösen.

Verschachtelung einer funktionalen Komponente

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

import Link from 'next/link'
import React from 'react'

// Definieren Sie den Props-Typ für MyButton
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}

// Verwenden Sie React.ForwardRefRenderFunction, um den weitergeleiteten Ref korrekt zu typisieren
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
}

// Verwenden Sie React.forwardRef, um die Komponente einzuwickeln
const ForwardedMyButton = React.forwardRef(MyButton)

export default function Page() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

import Link from 'next/link'
import React from 'react'

// `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}>
      Click Me
    </a>
  )
})

// Fügen Sie einen Anzeigenamen für die Komponente hinzu (nützlich für Debugging)
MyButton.displayName = 'MyButton'

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

URL ersetzen statt hinzufügen

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

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/about" replace>
      Über uns
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/about" replace>
      Über uns
    </Link>
  )
}

Scrollen zum Seitenanfang deaktivieren

Das Standard-Scrollverhalten von <Link> in Next.js ist das Beibehalten der Scrollposition, ähnlich wie Browser bei der Navigation zurück und vorwärts verfahren. Wenn Sie zu einer neuen Page navigieren, bleibt die Scrollposition erhalten, solange die Page im Viewport sichtbar ist.

Falls die Page jedoch nicht im Viewport sichtbar ist, scrollt Next.js zum obersten Element der Page. Wenn Sie dieses Verhalten deaktivieren möchten, können Sie scroll={false} an die <Link>-Komponente oder scroll: false an router.push() oder router.replace() übergeben.

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      Deaktiviert das Scrollen zum Seitenanfang
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      Deaktiviert das Scrollen zum Seitenanfang
    </Link>
  )
}

Verwendung von router.push() oder router.replace():

// useRouter
import { useRouter } from 'next/navigation'

const router = useRouter()

router.push('/dashboard', { scroll: false })

Prefetching von Links in Middleware

Es ist üblich, Middleware für Authentifizierung oder andere Zwecke zu verwenden, die eine Umleitung 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 Anfragen an die Middleware zu vermeiden, um die korrekte Route für das Prefetching zu ermitteln.

Beispiel: Wenn Sie eine /dashboard-Route bereitstellen möchten, die authentifizierte und Besucher-Ansichten hat, können Sie folgendes in Ihrer Middleware hinzufügen, um den Benutzer auf die richtige Seite umzuleiten:

import { NextResponse } from 'next/server'

export function middleware(request: Request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', request.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', request.url))
    }
  }
}

import { NextResponse } from 'next/server'

export function middleware(request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', request.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', request.url))
    }
  }
}

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

'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // Ihr Authentifizierungs-Hook

export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // Ihr Authentifizierungs-Hook

export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

Sie können die onNavigate-Prop verwenden, um die Navigation zu blockieren, wenn bestimmte Bedingungen erfüllt sind, z.B. wenn ein Formular ungespeicherte Änderungen enthält. Wenn Sie die Navigation über mehrere Komponenten in Ihrer App hinweg blockieren müssen (z.B. um die Navigation von jedem Link zu verhindern, während ein Formular bearbeitet wird), bietet React Context eine saubere Möglichkeit, diesen Blockierstatus zu teilen. Erstellen Sie zunächst einen Context, um den Blockierstatus der Navigation zu verfolgen:

'use client'

import { createContext, useState, useContext } from 'react'

interface NavigationBlockerContextType {
  isBlocked: boolean
  setIsBlocked: (isBlocked: boolean) => void
}

export const NavigationBlockerContext =
  createContext<NavigationBlockerContextType>({
    isBlocked: false,
    setIsBlocked: () => {},
  })

export function NavigationBlockerProvider({
  children,
}: {
  children: React.ReactNode
}) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

'use client'

import { createContext, useState, useContext } from 'react'

export const NavigationBlockerContext = createContext({
  isBlocked: false,
  setIsBlocked: () => {},
})

export function NavigationBlockerProvider({ children }) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

Erstellen Sie eine Formularkomponente, die den Context verwendet:

'use client'

import { useNavigationBlocker } from '../contexts/navigation-blocker'

export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Speichern</button>
    </form>
  )
}

'use client'

import { useNavigationBlocker } from '../contexts/navigation-blocker'

export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Speichern</button>
    </form>
  )
}

Erstellen Sie eine benutzerdefinierte Link-Komponente, die die Navigation blockiert:

'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

interface CustomLinkProps extends React.ComponentProps<typeof Link> {
  children: React.ReactNode
}

export function CustomLink({ children, ...props }: CustomLinkProps) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('Sie haben ungespeicherte Änderungen. Trotzdem verlassen?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

export function CustomLink({ children, ...props }) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('Sie haben ungespeicherte Änderungen. Trotzdem verlassen?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

Erstellen Sie eine Navigationskomponente:

'use client'

import { CustomLink as Link } from './custom-link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">Startseite</Link>
      <Link href="/about">Über uns</Link>
    </nav>
  )
}

'use client'

import { CustomLink as Link } from './custom-link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">Startseite</Link>
      <Link href="/about">Über uns</Link>
    </nav>
  )
}

Schließlich umschließen Sie Ihre App mit dem NavigationBlockerProvider im Root-Layout und verwenden die Komponenten in Ihrer Seite:

import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}

import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}

Verwenden Sie dann die Nav- und Form-Komponenten in Ihrer Seite:

import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Willkommen im Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}

import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Willkommen im Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}

Wenn ein Benutzer versucht, mit CustomLink wegzunavigieren, während das Formular ungespeicherte Änderungen enthält, wird er aufgefordert, dies zu bestätigen, bevor er die Seite verlässt.

Versionsverlauf

Version	Änderungen
`v15.3.0`	`onNavigate`-API hinzugefügt
`v13.0.0`	Benötigt kein untergeordnetes `<a>`-Tag mehr. Ein Codemod wird bereitgestellt, um Ihre Codebasis automatisch zu aktualisieren.
`v10.0.0`	`href`-Props, die auf eine dynamische Route verweisen, werden automatisch aufgelöst und benötigen keine `as`-Prop mehr.
`v8.0.0`	Verbesserte Prefetching-Leistung.
`v1.0.0`	`next/link` eingeführt.