useRouter

Der useRouter-Hook ermöglicht es Ihnen, Routen programmatisch innerhalb von 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>
  )
}

'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 (History API) ein.
router.replace(href: string, { scroll: boolean }): Führt eine clientseitige Navigation zur angegebenen Route durch, ohne einen neuen Eintrag in den Browser-Verlauf (History API) einzufügen.
router.refresh(): Aktualisiert die aktuelle Route. Sendet eine neue Anfrage an den Server, lädt Daten erneut und rendert Server Components neu. Der Client fügt die aktualisierte React Server Component-Nutzlast zusammen, ohne unberührte clientseitige React-Zustände (z.B. useState) oder Browser-Zustände (z.B. Scroll-Position) zu verlieren.
router.prefetch(href: string): Prefetch der angegebenen 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() könnte dasselbe Ergebnis erzeugen, wenn Fetch-Anfragen zwischengespeichert sind. Andere dynamische APIs wie cookies und headers könnten 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 wird durch usePathname() ersetzt.
Das query-Objekt wurde entfernt und wird durch useSearchParams() ersetzt.
router.events wurde ersetzt. Siehe unten.

Vollständige Migrationsanleitung ansehen.

Beispiele

Router-Events

Sie können auf Seitenänderungen hö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 '...'
}

Die in ein Layout importiert werden kann.

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 Scrolls nach oben

Standardmäßig scrollt Next.js beim Navigieren zu einer neuen Route nach oben. 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>
  )
}

'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()