re:re:actable
Урок 103 минуты чтения

Как работает useRouter в App Router

На этой странице
Кратко

useRouter из next/navigation — клиентский хук для программного перехода, управления историей браузера и обновления серверного содержимого текущего маршрута.

Вопрос

Как перейти на другой адрес после действия пользователя и чем push, replace и refresh отличаются друг от друга?

Основная идея

Обычный переход лучше описывать ссылкой Link: у нее есть адрес и стандартное поведение браузера. Иногда навигация зависит от результата операции — например, после сохранения формы нужно открыть страницу созданного объекта. Тогда маршрут меняют из кода.

Хук вызывают в клиентском компоненте. В App Router нужен импорт next/navigation; похожий next/router предназначен для Pages Router.

Методы и соседние хуки

APIЧто делает
router.push(href)Переход с новой записью в истории
router.replace(href)Переход с заменой текущей записи (после входа, смены фильтра)
router.back() / router.forward()Шаг по истории (закрыть модалку intercepting route)
router.refresh()Перезапросить серверные данные текущего маршрута, не теряя клиентского состояния
router.prefetch(href)Предзагрузить маршрут вручную
usePathname()Текущий путь (/catalog/books)
useSearchParams()Query-параметры (только чтение; оборачивай компонент в Suspense)
useParams()Динамические параметры в клиентском компоненте
redirect() / permanentRedirect()Редирект на сервере (Server Component, Action) — не хук
Pages Router: import { useRouter } from "next/router"      → router.query, router.pathname, router.events
App Router:   import { useRouter } from "next/navigation"  → только навигация; путь и параметры — отдельные хуки

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

// app/catalog/page.tsx
"use client";
 
import { useRouter } from "next/navigation";
 
export default function CatalogPage() {
  const router = useRouter();
 
  return (
    <main>
      <h1>Каталог</h1>
      <button onClick={() => router.push("/catalog?sort=price")}>
        Открыть сортировку по цене
      </button>
      <button onClick={() => router.replace("/catalog")}>
        Убрать параметры из текущего адреса
      </button>
      <button onClick={() => router.back()}>Назад</button>
      <button onClick={() => router.refresh()}>Обновить содержимое</button>
    </main>
  );
}

Первая кнопка меняет URL и добавляет запись истории. Вторая заменяет текущую запись, не добавляя еще одну. Кнопка «Назад» обращается к истории браузера. Пример показывает управление адресом: для реальной сортировки нужно дополнительно прочитать параметр и отсортировать товары.

Что важно помнить

router.refresh() делает запрос серверного содержимого текущего маршрута и объединяет результат с интерфейсом. Он не равен полной перезагрузке документа и не очищает автоматически постоянный Data Cache. Если данные закэшированы, сервер может вернуть прежние значения. Состояние незатронутых клиентских компонентов может сохраниться.

Для чтения URL предусмотрены отдельные хуки: usePathname, useParams и useSearchParams. В статически рендеримых маршрутах использование useSearchParams может требовать границу Suspense.

Не передавай непроверенный пользовательский текст в push и replace: адрес нужно формировать из допустимых значений. back() может увести за пределы сайта, если предыдущая запись истории была внешней.

Мини-шпаргалка

  • push добавляет запись истории; replace заменяет текущую.
  • back и forward перемещаются по истории.
  • refresh обновляет серверное содержимое, но не отменяет весь кэш.
  • Для чтения URL используют другие хуки.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам