useRouter

Хук useRouter позволяет программно изменять маршруты внутри Клиентских компонентов (Client Components).

Рекомендация: Используйте компонент <Link> для навигации, если у вас нет специальных требований для использования 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 }): Выполняет клиентскую навигацию к указанному маршруту. Добавляет новую запись в историю браузера (browser's history).
router.replace(href: string, { scroll: boolean }): Выполняет клиентскую навигацию к указанному маршруту без добавления новой записи в историю браузера (browser's history stack).
router.refresh(): Обновляет текущий маршрут. Делает новый запрос к серверу, повторно загружает данные и перерендеривает Серверные компоненты (Server Components). Клиент объединит обновлённые данные React Server Component без потери состояния клиентского React (например, useState) или состояния браузера (например, позиции прокрутки).
router.prefetch(href: string): Предзагружает (Prefetch) указанный маршрут для более быстрых клиентских переходов.
router.back(): Переходит назад к предыдущему маршруту в истории браузера.
router.forward(): Переходит вперёд к следующей странице в истории браузера.

Полезно знать:

Не передавайте непроверенные или неочищенные URL в router.push или router.replace, так как это может сделать ваш сайт уязвимым к межсайтовому скриптингу (XSS). Например, URL с javascript:, переданные в router.push или router.replace, будут выполнены в контексте вашей страницы.

Компонент <Link> автоматически предзагружает маршруты, когда они становятся видимыми в области просмотра.

refresh() может дать тот же результат, если fetch-запросы закэшированы. Другие динамические API, такие как cookies и headers, также могут изменить ответ.

Миграция с `next/router`

Хук useRouter должен импортироваться из next/navigation, а не из next/router при использовании App Router
Строка pathname удалена и заменена на usePathname()
Объект query удалён и заменён на useSearchParams()
router.events заменён. Смотрите ниже.

Полное руководство по миграции.

Примеры

События маршрутизатора (Router events)

Вы можете отслеживать изменения страницы, комбинируя другие хуки Клиентских компонентов, такие как usePathname и 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)
    // Теперь можно использовать текущий URL
    // ...
  }, [pathname, searchParams])

  return '...'
}

Который можно импортировать в 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>
  )
}

Полезно знать: <NavigationEvents> обёрнут в Suspense boundary, потому что useSearchParams() вызывает клиентский рендеринг до ближайшей границы Suspense во время статического рендеринга (static rendering). Подробнее.

Отключение прокрутки к верху страницы

По умолчанию Next.js прокручивает страницу к верху при переходе на новый маршрут. Это поведение можно отключить, передав scroll: false в router.push() или 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>
  )
}

История версий

Версия	Изменения
`v13.0.0`	Добавлен `useRouter` из `next/navigation`.

useRouter()