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 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 de 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 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 sanitizadas 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 rutas cuando se vuelven visibles en el viewport.

refresh() podría reproducir el mismo resultado si las solicitudes 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
El string pathname ha sido eliminado y reemplazado 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. Aprender más.

Deshabilitar desplazamiento al inicio

Por defecto, Next.js se desplazará al inicio 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()