useRouter

Le hook useRouter permet de changer programmatiquement les routes dans les composants clients.

Recommandation : Utilisez le composant <Link> pour la navigation, sauf si vous avez un besoin spécifique nécessitant useRouter.

'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 }) : Effectue une navigation côté client vers la route fournie. Ajoute une nouvelle entrée dans la pile d'historique du navigateur.
router.replace(href: string, { scroll: boolean }) : Effectue une navigation côté client vers la route fournie sans ajouter d'entrée dans la pile d'historique du navigateur.
router.refresh() : Rafraîchit la route actuelle. Effectue une nouvelle requête vers le serveur, récupère les données et re-rend les composants serveur. Le client fusionne la nouvelle charge utile des composants serveur React sans perdre l'état côté client React (ex: useState) ou du navigateur (ex: position de défilement).
router.prefetch(href: string) : Précharge la route fournie pour des transitions côté client plus rapides.
router.back() : Navigue vers la route précédente dans la pile d'historique du navigateur.
router.forward() : Navigue vers la page suivante dans la pile d'historique du navigateur.

Bon à savoir :

Le composant <Link> précharge automatiquement les routes lorsqu'elles deviennent visibles dans la fenêtre.

refresh() peut produire le même résultat si les requêtes sont mises en cache. D'autres fonctions dynamiques comme cookies et headers peuvent aussi modifier la réponse.

Migration depuis `next/router`

Le hook useRouter doit être importé depuis next/navigation et non next/router lors de l'utilisation du routeur App.
La chaîne pathname a été supprimée et remplacée par usePathname().
L'objet query a été supprimé et remplacé par useSearchParams().
router.events a été remplacé. Voir ci-dessous.

Consultez le guide complet de migration.

Exemples

Événements du routeur

Vous pouvez écouter les changements de page en combinant d'autres hooks de composants clients comme usePathname et useSearchParams.

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)
    // Vous pouvez maintenant utiliser l'URL courante
    // ...
  }, [pathname, searchParams])

  return null
}

Qui peut être importé dans une mise en page.

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

Bon à savoir : <NavigationEvents> est encapsulé dans une limite Suspense car useSearchParams() provoque un rendu côté client jusqu'à la limite Suspense la plus proche pendant le rendu statique. En savoir plus.

Désactivation de la restauration du défilement

Par défaut, Next.js défile vers le haut de la page lors de la navigation vers une nouvelle route. Vous pouvez désactiver ce comportement en passant scroll: false à router.push() ou router.replace().

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

Historique des versions

Version	Changements
`v13.0.0`	`useRouter` depuis `next/navigation` introduit.

useRouter()