Как работает 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 используют другие хуки.