Активные и точные совпадения ссылок

Основная концепция активных ссылок

TanStack Router предоставляет мощный механизм для управления состоянием маршрутов и определения того, какая ссылка считается активной. Активная ссылка — это та, путь которой совпадает с текущим URL приложения. Для корректной работы навигации важно различать два типа совпадений: точное совпадение и частичное совпадение.

  • Точное совпадение (exact) – ссылка считается активной только если путь полностью совпадает с текущим URL.
  • Частичное совпадение (partial) – ссылка считается активной, если текущий URL начинается с пути ссылки. Частичное совпадение полезно для подсветки пунктов меню, когда пользователь находится в разделе с вложенными страницами.

Пример определения активной ссылки:

import { Link, useIsActive } from '@tanstack/router';

function Menu() {
  const isActiveHome = useIsActive({ to: '/' });

  return (
    <nav>
      <Link to="/" active={isActiveHome ? 'active' : ''}>Главная</Link>
    </nav>
  );
}

В этом примере useIsActive возвращает булевское значение, которое определяет, следует ли применять CSS-класс для активного состояния.

Точное совпадение маршрутов

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

<Link to="/" exact>Главная</Link>
<Link to="/about">О нас</Link>

Если URL приложения /about, то ссылка на / не будет активной, что предотвращает неправильное подсвечивание главной страницы.

Частичное совпадение и подсветка вложенных маршрутов

Частичное совпадение используется для меню с несколькими уровнями навигации. Оно позволяет выделять родительский пункт, если пользователь находится на одной из вложенных страниц.

<Link to="/dashboard" activeOptions={{ exact: false }}>Панель</Link>

Здесь activeOptions={{ exact: false }} говорит, что активное состояние ссылки включается для всех URL, начинающихся с /dashboard, включая /dashboard/settings или /dashboard/stats.

Использование хуков для проверки активности

TanStack Router предоставляет хук useMatch, который позволяет более гибко проверять, совпадает ли текущий маршрут с заданным паттерном.

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

function Sidebar() {
  const match = useMatch({ to: '/dashboard/settings' });

  return (
    <div className={match ? 'highlight' : ''}>
      Настройки
    </div>
  );
}

В этом примере useMatch возвращает true, если текущий URL полностью совпадает с /dashboard/settings. Для частичного совпадения можно использовать опцию exact: false.

Настройка поведения активных ссылок через activeOptions

Компоненты Link и хук useIsActive поддерживают объект activeOptions, где можно указывать дополнительные параметры:

  • exact: boolean – включение точного или частичного совпадения
  • includeHash: boolean – учитывать хэш в URL
  • includeQuery: boolean – учитывать параметры запроса

Пример с учетом query-параметров:

<Link
  to="/search"
  activeOptions={{ exact: true, includeQuery: true }}
>
  Результаты поиска
</Link>

Теперь ссылка будет активной только при точном совпадении пути и query-параметров, например /search?term=router.

Стилизация активных ссылок

Для удобства TanStack Router позволяет назначать класс активной ссылки напрямую через свойство active:

<Link
  to="/profile"
  active="active-link"
>
  Профиль
</Link>

При этом при срабатывании условия активности к элементу автоматически применяется CSS-класс active-link. Комбинируя это с точными и частичными совпадениями, можно создавать гибкую навигацию с четкой визуальной подсветкой текущего маршрута.

Сравнение подходов: exact vs partial

Параметр Применение Риск ошибок
exact Главная страница, отдельные страницы Подсветка родителя не срабатывает для вложенных страниц
partial Меню с вложенной навигацией Может подсвечивать несколько ссылок одновременно, если пути пересекаются

Эффективное использование этих двух подходов обеспечивает точное управление активным состоянием ссылок и предотвращает визуальные несоответствия в интерфейсе.

Резюме по использованию

  • Для главного маршрута всегда рекомендуется использовать exact: true.
  • Для разделов с вложенной навигацией удобнее использовать exact: false или partial match.
  • activeOptions позволяет гибко учитывать query-параметры и хэши.
  • Хуки useIsActive и useMatch дают возможность программно проверять активность и применять кастомные стили.

Такой подход обеспечивает прозрачную и предсказуемую работу навигации в приложениях на базе TanStack Router.

Оглавление