useRouter

Le hook useRouter vous permet de changer programmatiquement les routes dans les Composants Client.

Recommandation : Utilisez le composant <Link> pour la navigation, sauf si vous avez un besoin spécifique nécessitant l'utilisation de 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>
  )
}

`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 de nouvelle 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 fusionnera la nouvelle charge utile du Composant Serveur React sans perdre l'état côté client React (par exemple useState) ou l'état du navigateur (par exemple la 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 :

Vous ne devez pas envoyer d'URL non fiables ou non assainies à router.push ou router.replace, car cela peut exposer votre site à des vulnérabilités de cross-site scripting (XSS). Par exemple, les URL javascript: envoyées à router.push ou router.replace seront exécutées dans le contexte de votre page.

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

refresh() pourrait produire le même résultat si les requêtes fetch sont mises en cache. D'autres API dynamiques comme cookies et headers pourraient également 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 Composant Client 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 '...'
}

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ésactiver le défilement vers le haut

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

Historique des versions

Version	Changements
`v13.0.0`	Introduction de `useRouter` depuis `next/navigation`.

useRouter()