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

`useRouter()`

router.push(href: string, { scroll: boolean }): Realiza una navegación del lado del cliente (client-side) a la ruta proporcionada. Añade una nueva entrada en 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 en 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.

Importante:

No debe enviar URLs no confiables o no saneadas a router.push o router.replace, ya que esto puede exponer su sitio a vulnerabilidades de cross-site scripting (XSS). Por ejemplo, URLs con javascript: enviadas a router.push o router.replace se ejecutarán en el contexto de su página.

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

refresh() podría producir el mismo resultado si las solicitudes de fetch están en caché. Otras APIs 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 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 más abajo.

Ver la guía completa de migración.

Ejemplos

Eventos del Router

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

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

Importante: <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.

Desactivar desplazamiento al inicio

Por defecto, Next.js se desplazará al inicio de la página al navegar a una nueva ruta. Puede desactivar 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>
  )
}

Historial de versiones

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

useRouter()