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

Referenz

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

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

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

scroll

Standardwert: true. Das standardmäßige Scrollverhalten von <Link> in Next.js ist die Beibehaltung der Scrollposition, ähnlich wie Browser mit der Navigation vor und zurück umgehen. Wenn Sie zu einer neuen Seite navigieren, bleibt die Scrollposition gleich, solange die Seite im Viewport sichtbar ist. Wenn die Seite jedoch nicht im Viewport sichtbar ist, scrollt Next.js zum obersten Element der Seite.

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

Gut zu wissen: Next.js prüft scroll: false, bevor es das Scrollverhalten verwaltet. Wenn das Scrollen aktiviert ist, identifiziert es den relevanten DOM-Knoten 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 sticky Positionierung und nicht sichtbaren Elementen, die mit getBoundingClientRect berechnet werden. 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>
  )
}

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 vor, um die Leistung der clientseitigen Navigation zu verbessern. Wenn die vorab geladenen Daten abgelaufen sind, wenn der Benutzer über einen <Link /> hovered, versucht Next.js, sie erneut vorzuladen. Prefetching ist nur in der Produktion aktiviert.

Die folgenden 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 (einschließlich aller Daten) vorab geladen. Für dynamische Routen wird der Teil der Route bis zum nächsten Segment mit einer loading.js-Grenze vorab geladen.
• true: Die vollständige Route wird für statische und dynamische Routen vorab geladen.
• 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>
  )
}

onNavigate

Ein Event-Handler, der während der clientseitigen Navigation aufgerufen wird. Der Handler empfängt 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('Navigiere...')

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

Gut zu wissen: Obwohl onClick und onNavigate ähnlich erscheinen mögen, 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 Modifikatortasten (Strg/Cmd + Klick) wird onClick ausgeführt, aber nicht onNavigate, 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 Blog-Posts 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>
  )
}

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

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

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 eingebaute 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 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 wrappen:

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 zu wrappen
const ForwardedMyButton = React.forwardRef(MyButton)

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

URL ersetzen statt pushen

Das Standardverhalten der Link-Komponente besteht darin, eine neue URL in den history-Stack zu pushen. 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>
      About us
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

Scrollen zum Seitenanfang deaktivieren

Das Standard-Scrollverhalten von <Link> in Next.js ist die Beibehaltung 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.

Wenn die Page jedoch nicht im Viewport sichtbar ist, scrollt Next.js zum oberen Rand des ersten Page-Elements. 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>
  )
}

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

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

Blockieren der Navigation

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

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

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

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

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

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

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