useRouter

Der useRouter-Hook ermöglicht es Ihnen, Routen programmatisch in Client Components zu ändern.

Empfehlung: Verwenden Sie die <Link>-Komponente für die Navigation, es sei denn, Sie haben einen spezifischen Grund, useRouter zu verwenden.

'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

`useRouter()`

router.push(href: string, { scroll: boolean }): Führt eine clientseitige Navigation zur angegebenen Route durch. Fügt einen neuen Eintrag in den Browser-Verlauf ein.
router.replace(href: string, { scroll: boolean }): Führt eine clientseitige Navigation zur angegebenen Route durch, ohne einen neuen Eintrag in den Browser-Verlauf hinzuzufügen.
router.refresh(): Aktualisiert die aktuelle Route. Dabei wird eine neue Anfrage an den Server gesendet, Datenanfragen neu abgerufen und Server Components neu gerendert. Der Client führt die aktualisierte React Server Component-Nutzlast zusammen, ohne nicht betroffene clientseitige React-Zustände (z.B. useState) oder Browser-Zustände (z.B. Scroll-Position) zu verlieren.
router.prefetch(href: string): Prefetched die angegebene Route für schnellere clientseitige Übergänge.
router.back(): Navigiert zurück zur vorherigen Route im Browser-Verlauf.
router.forward(): Navigiert vorwärts zur nächsten Seite im Browser-Verlauf.

Wissenswert:

Sie sollten keine nicht vertrauenswürdigen oder nicht bereinigten URLs an router.push oder router.replace senden, da dies Ihre Seite für Cross-Site-Scripting (XSS)-Sicherheitslücken öffnen kann. Beispielsweise werden javascript:-URLs, die an router.push oder router.replace gesendet werden, im Kontext Ihrer Seite ausgeführt.

Die <Link>-Komponente prefetcht Routen automatisch, sobald sie im Viewport sichtbar werden.

refresh() kann das gleiche Ergebnis erzeugen, wenn Fetch-Anfragen zwischengespeichert sind. Andere dynamische APIs wie cookies und headers können ebenfalls die Antwort ändern.

Migration von `next/router`

Der useRouter-Hook sollte aus next/navigation und nicht aus next/router importiert werden, wenn der App Router verwendet wird.
Die pathname-Zeichenkette wurde entfernt und durch usePathname() ersetzt.
Das query-Objekt wurde entfernt und durch useSearchParams() ersetzt.
router.events wurde ersetzt. Siehe unten.

Vollständigen Migrationsleitfaden anzeigen.

Beispiele

Router-Ereignisse

Sie können Seitenänderungen abhören, indem Sie andere Client Component-Hooks wie usePathname und useSearchParams kombinieren.

app/components/navigation-events.js

'use client'

import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

export function NavigationEvents() {
  const pathname = usePathname()
  const searchParams = useSearchParams()

  useEffect(() => {
    const url = `${pathname}?${searchParams}`
    console.log(url)
    // Sie können jetzt die aktuelle URL verwenden
    // ...
  }, [pathname, searchParams])

  return '...'
}

Dies kann in ein Layout importiert werden.

app/layout.js

import { Suspense } from 'react'
import { NavigationEvents } from './components/navigation-events'

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

        <Suspense fallback={null}>
          <NavigationEvents />
        </Suspense>
      </body>
    </html>
  )
}

Wissenswert: <NavigationEvents> ist in eine Suspense-Boundary eingebettet, weil useSearchParams() während des statischen Renderings clientseitiges Rendering bis zur nächsten Suspense-Boundary verursacht. Mehr erfahren.

Deaktivieren des Scrollens nach oben

Standardmäßig scrollt Next.js beim Navigieren zu einer neuen Route nach oben auf der Seite. Sie können dieses Verhalten deaktivieren, indem Sie scroll: false an router.push() oder router.replace() übergeben.

'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button
      type="button"
      onClick={() => router.push('/dashboard', { scroll: false })}
    >
      Dashboard
    </button>
  )
}

Versionsverlauf

Version	Änderungen
`v13.0.0`	`useRouter` aus `next/navigation` eingeführt.

useRouter()