useNavigate для программной навигации

useNavigate — это хук библиотеки TanStack Router, который предоставляет механизм для программного управления навигацией внутри приложения. Он заменяет необходимость прямого взаимодействия с <Link> и позволяет управлять переходами динамически, исходя из состояния приложения, данных пользователя или других условий.

Импорт и базовое использование

Для начала необходимо импортировать хук из библиотеки:

import { useNavigate } from '@tanstack/router';

После этого useNavigate можно использовать внутри функционального компонента:

function MyComponent() {
  const navigate = useNavigate();

  const goToHome = () => {
    navigate({ to: '/home' });
  };

  return (
    <button onCl ick={goToHome}>Перейти на главную</button>
  );
}

В этом примере navigate принимает объект с ключом to, который указывает путь маршрута. Это минимальный синтаксис, позволяющий выполнять переходы между страницами.

Параметры объекта navigate

Функция navigate поддерживает несколько полезных опций:

  • to — обязательное поле, путь маршрута или объект маршрута.
  • replace — если установлено true, переход заменяет текущую запись в истории, а не добавляет новую.
  • state — объект состояния, который можно передать маршруту, аналог location.state в обычных маршрутизаторах.
  • search — объект или строка с параметрами query.

Пример использования всех опций:

navigate({
  to: '/profile',
  replace: true,
  state: { referrer: 'dashboard' },
  search: { tab: 'settings' }
});

Этот вызов заменяет текущий маршрут на /profile, передает состояние и добавляет query-параметр ?tab=settings.

Навигация с динамическими параметрами

TanStack Router поддерживает маршруты с динамическими сегментами, и useNavigate легко позволяет переходить к таким маршрутам:

const navigate = useNavigate();
const userId = 42;

navigate({
  to: '/users/$userId',
  params: { userId }
});

Ключевой момент: для динамических сегментов путь задается с $, а значения передаются через объект params. Это гарантирует корректное формирование URL без ручной подстановки строк.

Программная навигация по условию

Часто требуется навигация после выполнения асинхронной операции или проверки условия:

async function handleLogin(credentials) {
  const success = await api.login(credentials);
  if (success) {
    navigate({ to: '/dashboard' });
  } else {
    navigate({ to: '/login', state: { error: 'Неверный логин или пароль' } });
  }
}

Такой подход позволяет централизованно управлять логикой переходов, минимизируя дублирование <Link> компонентов в шаблонах.

Использование с историей браузера

Опция replace позволяет интегрировать useNavigate с историей браузера, управляя стеком переходов:

  • replace: true — переход заменяет текущую запись.
  • replace: false (по умолчанию) — переход добавляется в стек истории.

Пример:

navigate({ to: '/settings', replace: true });

Это удобно для редиректов после авторизации, когда не требуется возможность возврата на страницу входа кнопкой «Назад».

Переход на предыдущий маршрут

useNavigate позволяет легко реализовать возврат на предыдущий маршрут через отрицательное значение:

navigate({ to: -1 });

Здесь -1 соответствует аналогии с history.back(). Также можно указать другие отрицательные числа для возврата на несколько шагов назад.

Интеграция с query-параметрами и состоянием

С помощью useNavigate можно управлять query-параметрами и состоянием маршрута без перезагрузки страницы:

navigate({
  to: '/search',
  search: { q: 'tanstack', page: 2 },
  state: { from: 'homepage' }
});

В этом примере URL автоматически преобразуется в /search?q=tanstack&page=2, а объект состояния доступен на целевой странице через useLocation или аналогичные API TanStack Router.

Программная навигация с колбэками

Для более сложных сценариев, например после сохранения данных на сервере, можно комбинировать useNavigate с колбэками:

function handleSubmit(formData) {
  api.saveData(formData).then(response => {
    navigate({ to: `/results/${response.id}` });
  });
}

Это обеспечивает плавный пользовательский опыт, где навигация происходит автоматически после успешного завершения операций.

Поддержка TypeScript

useNavigate отлично интегрируется с TypeScript благодаря строгой типизации маршрутов:

const navigate = useNavigate<MyRoutes>();

navigate({ to: 'profile', params: { userId: 10 } });

Типизация помогает избежать ошибок передачи неверных параметров и обеспечивает автодополнение в IDE.

Итоговые особенности useNavigate

  • Поддержка динамических сегментов маршрутов через params.
  • Управление историей через replace и отрицательные значения.
  • Передача состояния и query-параметров без лишних компонентов.
  • Прямая интеграция с TypeScript для безопасной навигации.
  • Возможность программной навигации после асинхронных операций и проверок условий.

Эти возможности делают useNavigate мощным инструментом для создания гибких и динамичных маршрутов в приложениях на TanStack Router.

Оглавление