useRouter

El hook useRouter permite cambiar rutas programáticamente dentro de Componentes del Cliente.

Recomendación: Utilice el componente <Link> para navegación a menos que tenga un requisito específico para usar 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 }): Realiza una navegación del lado del cliente a la ruta proporcionada. Añade una nueva entrada a la pila de historial del navegador.
router.replace(href: string, { scroll: boolean }): Realiza una navegación del lado del cliente a la ruta proporcionada sin añadir una nueva entrada a la pila de historial del navegador.
router.refresh(): Actualiza la ruta actual. Hace una nueva solicitud al servidor, vuelve a obtener solicitudes de datos y vuelve a renderizar Componentes del Servidor. El cliente fusionará la carga útil actualizada del Componente del Servidor React sin perder el estado del lado del cliente de React (ej. useState) o el estado del navegador (ej. posición de desplazamiento).
router.prefetch(href: string): Prefetch de la ruta proporcionada para transiciones más rápidas del lado del cliente.
router.back(): Navega hacia atrás a la ruta anterior en la pila de historial del navegador.
router.forward(): Navega hacia adelante a la siguiente página en la pila de historial del navegador.

Es bueno saber:

El componente <Link> hace prefetch automáticamente de las rutas cuando son visibles en el viewport.

refresh() podría reproducir el mismo resultado si las solicitudes fetch están en caché. Otras funciones dinámicas como cookies y headers también podrían cambiar la respuesta.

Migración desde `next/router`

El hook useRouter debe importarse desde next/navigation y no desde next/router cuando se usa el Enrutador de Aplicación (App Router)
La cadena pathname ha sido eliminada y reemplazada por usePathname()
El objeto query ha sido eliminado y reemplazado por useSearchParams()
router.events ha sido reemplazado. Ver abajo.

Ver la guía completa de migración.

Ejemplos

Eventos del enrutador

Puede escuchar cambios de página componiendo otros hooks de Componentes del Cliente como usePathname y 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)
    // Ahora puede usar la URL actual
    // ...
  }, [pathname, searchParams])

  return null
}

Que puede importarse en un layout.

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

Es bueno saber: <NavigationEvents> está envuelto en un límite Suspense porque useSearchParams() causa renderizado del lado del cliente hasta el límite Suspense más cercano durante renderizado estático. Aprenda más.

Deshabilitar restauración de desplazamiento

Por defecto, Next.js desplazará hacia la parte superior de la página al navegar a una nueva ruta. Puede deshabilitar este comportamiento pasando scroll: false a router.push() o 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>
  )
}

Historial de versiones

Versión	Cambios
`v13.0.0`	Se introdujo `useRouter` desde `next/navigation`.

useRouter()