﻿---
description: Горизонтальная панель с кнопками-ссылками для быстрой навигации между подразделами или управления контентом.
keywords:
  - SubnavigationButton
---

# SubnavigationBar \[tag:component]

Горизонтальная панель с кнопками-ссылками для быстрой навигации между подразделами или управления контентом.
Используется как элемент вторичной навигации внутри раздела. Поддерживает горизонтальную прокрутку контента
с индикацией наличия скрытых элементов (стрелки навигации).

```jsx
<SubnavigationBar>
  <SubnavigationButton onClick={() => {}}>Мой размер</SubnavigationButton>
  <SubnavigationButton onClick={() => {}}>В наличии</SubnavigationButton>
  <SubnavigationButton onClick={() => {}}>Высокий рейтинг</SubnavigationButton>
  <SubnavigationButton onClick={() => {}}>Избранное</SubnavigationButton>
</SubnavigationBar>
```

## Когда использовать

* Переключение между связанными подразделами.
* Активации фильтров или сортировок.
* Быстрый доступ к модальным окнам.
* Группировка действий в компактном пространстве.

## Режимы работы

### Фиксированная ширина

`fixed={true}` — равномерно распределяет пространство между элементами:

* Автоматически отключает горизонтальную прокрутку.
* Требует точного контроля за содержимым (рекомендуется 2-5 элементов).
* Для длинных текстов используйте `textLevel` у `SubnavigationButton`.

### Горизонтальная прокрутка

`fixed={false}` (по умолчанию) — активирует адаптивную прокрутку.
Поддерживает [свойства из HorizontalScroll](/components/horizontal-scroll):

* `showArrows` — управление видимостью стрелок;
* `getScrollToLeft`/`getScrollToRight` — кастомная логика прокрутки;
* `scrollAnimationDuration` — скорость анимации.

## Доступность (a11y) \[#a11y]

* Список элементов реализован с использованием семантического тега `ul`.
* Элементы списка оборачиваются в семантические теги `li`.

## SubnavigationButton \[#subnavigation-button] \[tag:component]

Кнопка/ссылка для использования внутри [`SubnavigationBar`](/components/subnavigation-bar). Предназначена для навигации между подразделами или управления
контентом (активация фильтров, открытие модальных окон).

```jsx
<SubnavigationButton onClick={() => {}} before={<Icon24FavoriteOutline />}>
  Избранное
</SubnavigationButton>
```

### Состояния

`selected` — выделяет кнопку как активную. Используйте для индикации текущего раздела или применённого фильтра.

```jsx
<SubnavigationBar>
  <SubnavigationButton selected onClick={() => {}}>
    Выбран
  </SubnavigationButton>
  <SubnavigationButton onClick={() => {}}>Не выбран</SubnavigationButton>
</SubnavigationBar>
```

### Режимы отображения

Задается свойством `mode`:

* `primary` — первичный вид для привлечения внимания;
* `secondary` — вторичный вид с полупрозрачным фоном;
* `outline` — вид с обводкой;
* `tertiary` — третичный вид без фона.

### Внешний вид

Задается свойством `appearance`.

#### `accent`

```jsx
<SubnavigationBar>
  <SubnavigationButton mode="primary" appearance="accent" selected onClick={() => {}}>
    primary accent selected
  </SubnavigationButton>
  <SubnavigationButton mode="primary" appearance="accent" onClick={() => {}}>
    primary accent
  </SubnavigationButton>
</SubnavigationBar>
<SubnavigationBar>
  <SubnavigationButton mode="secondary" appearance="accent" selected onClick={() => {}}>
    secondary accent selected
  </SubnavigationButton>
  <SubnavigationButton mode="secondary" appearance="accent" onClick={() => {}}>
    secondary accent
  </SubnavigationButton>
</SubnavigationBar>
<SubnavigationBar>
  <SubnavigationButton mode="outline" appearance="accent" selected onClick={() => {}}>
    outline accent selected
  </SubnavigationButton>
  <SubnavigationButton mode="outline" appearance="accent" onClick={() => {}}>
    outline accent
  </SubnavigationButton>
</SubnavigationBar>
<SubnavigationBar>
  <SubnavigationButton mode="tertiary" appearance="accent" selected onClick={() => {}}>
    tertiary accent selected
  </SubnavigationButton>
  <SubnavigationButton mode="tertiary" appearance="accent" onClick={() => {}}>
    tertiary accent
  </SubnavigationButton>
</SubnavigationBar>
```

#### `neutral`

```jsx
<SubnavigationBar>
  <SubnavigationButton mode="primary" appearance="neutral" selected onClick={() => {}}>
    primary neutral selected
  </SubnavigationButton>
  <SubnavigationButton mode="primary" appearance="neutral" onClick={() => {}}>
    primary neutral
  </SubnavigationButton>
</SubnavigationBar>
<SubnavigationBar>
  <SubnavigationButton mode="secondary" appearance="neutral" selected onClick={() => {}}>
    secondary neutral selected
  </SubnavigationButton>
  <SubnavigationButton mode="secondary" appearance="neutral" onClick={() => {}}>
    secondary neutral
  </SubnavigationButton>
</SubnavigationBar>
<SubnavigationBar>
  <SubnavigationButton mode="outline" appearance="neutral" selected onClick={() => {}}>
    outline neutral selected
  </SubnavigationButton>
  <SubnavigationButton mode="outline" appearance="neutral" onClick={() => {}}>
    outline neutral
  </SubnavigationButton>
</SubnavigationBar>
<SubnavigationBar>
  <SubnavigationButton mode="tertiary" appearance="neutral" selected onClick={() => {}}>
    tertiary neutral selected
  </SubnavigationButton>
  <SubnavigationButton mode="tertiary" appearance="neutral" onClick={() => {}}>
    tertiary neutral
  </SubnavigationButton>
</SubnavigationBar>
```

### Размеры и контент

Размер самой кнопки задается свойством `size`:

* `s` — компактный;
* `m` — стандартный;
* `l` — увеличенный.

`textLevel` — отдельно настраивает размер текста (1 — крупный, 3 — мелкий).
Полезно в режиме `fixed` у родительского [`SubnavigationBar`](/components/subnavigation-bar).

```jsx
<SubnavigationButton size="s" onClick={() => {}}>
  size="s"
</SubnavigationButton>
<SubnavigationButton size="m" onClick={() => {}}>
  size="m"
</SubnavigationButton>
<SubnavigationButton size="l" onClick={() => {}}>
  size="l"
</SubnavigationButton>
```

### Дополнительные элементы

* `before` — иконка перед текстом (рекомендуемый размер `24px`).
* `after` — счётчик или бейдж (рекомендуется использовать только `Counter size="s"` или `Badge`).
* `chevron` — добавляет стрелку-индикатор справа.

```jsx
<SubnavigationButton
  before={<Icon24Filter />}
  selected
  chevron
  after={
    <Counter size="s">
      <VisuallyHidden>Применено: </VisuallyHidden>3
    </Counter>
  }
  onClick={() => {}}
>
  Фильтры
</SubnavigationButton>
```

## Свойства и методы \[#api]

### SubnavigationBar

| Свойство                  | Тип                     | По умолчанию     | Описание                                                                                                                                     |
| ------------------------- | ----------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `arrowSize`               | `"s" \| "m"`            | `s`              | Размер стрелок.                                                                                                                              |
| `fixed`                   | `boolean`               | `false`          | Отключение возможности прокручивания компонента по горизонтали.                                                                              |
| `getRootRef`              | `Ref<HTMLDivElement>`   | `-`              |                                                                                                                                              |
| `getScrollToLeft`         | `ScrollPositionHandler` | `(x) => x - 240` | Функция для расчета величины прокрутки при нажатии на левую стрелку.                                                                         |
| `getScrollToRight`        | `ScrollPositionHandler` | `(x) => x + 240` | Функция для расчета величины прокрутки при нажатии на правую стрелку.                                                                        |
| `noPadding`               | `boolean`               | `false`          | Отключает отступы. Рекомендуется использовать с `mode="outline"` у [`SubnavigationButton`](https://vkui.io/components/subnavigation-button). |
| `ref`                     | `Ref<HTMLDivElement>`   | `-`              |                                                                                                                                              |
| `scrollAnimationDuration` | `number`                | `-`              | Длительность анимации скролла.                                                                                                               |
| `showArrows`              | `boolean \| "always"`   | `true`           | Показывать ли стрелки.                                                                                                                       |

### SubnavigationButton

| Свойство               | Тип                                                                                             | По умолчанию | Описание                                                                                                                                                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activated`            | `boolean`                                                                                       | `-`          | Позволяет управлять `activated`-состоянием извне.                                                                                                                                                                                                                                      |
| `activeClassName`      | `string`                                                                                        | `-`          | **Deprecated**: Since 7.3.0. Будет удалено в **VKUI v9**.  Используйте свойство `activeMode`.                                                                                                                                                                                          |
| `activeEffectDelay`    | `number`                                                                                        | `-`          | Длительность показа `active`-состояния.                                                                                                                                                                                                                                                |
| `activeMode`           | `StateModeLiteral`                                                                              | `-`          | Стиль подсветки active-состояния. Если передать произвольную строку, она добавится как css-класс во время active.                                                                                                                                                                      |
| `after`                | `ReactNode`                                                                                     | `-`          | Рекомендуется использовать только `<Counter size="s" />` или `<Badge />`.                                                                                                                                                                                                              |
| `appearance`           | `"accent" \| "neutral"`                                                                         | `accent`     | Тип внешнего вида кнопки.                                                                                                                                                                                                                                                              |
| `before`               | `ReactNode`                                                                                     | `-`          | Рекомендуется использовать только иконки с размером 24.                                                                                                                                                                                                                                |
| `borderRadiusMode`     | `"auto" \| "inherit"`                                                                           | `-`          | Задает border-radius элементу В режиме `auto` на маленьких экранах `border-radius: 0`, иначе определяется токеном `--vkui--size_border_radius--regular`.                                                                                                                               |
| `chevron`              | `boolean`                                                                                       | `-`          | Нужно ли отображать иконку `"chevron"`.                                                                                                                                                                                                                                                |
| `Component`            | `ElementType<any, keyof IntrinsicElements>`                                                     | `-`          |                                                                                                                                                                                                                                                                                        |
| `focusVisibleMode`     | `FocusVisibleMode`                                                                              | `-`          | Стиль аутлайна focus visible. Если передать произвольную строку, она добавится как css-класс при :focus-visible                                                                                                                                                                        |
| `getRootRef`           | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `hasActive`            | `boolean`                                                                                       | `-`          | Указывает, должен ли компонент реагировать на `active`-состояние.                                                                                                                                                                                                                      |
| `hasHover`             | `boolean`                                                                                       | `-`          | Указывает, должен ли компонент реагировать на `hover`-состояние.                                                                                                                                                                                                                       |
| `hasHoverWithChildren` | `boolean`                                                                                       | `-`          | Позволяет родительскому компоненту иметь `hovered`-cостояние при наведении на любой дочерний элемент. По умолчанию состояние hovered у родителя сбрасывается.  Присваивается родителькому компоненту.                                                                                  |
| `hoverClassName`       | `string`                                                                                        | `-`          | **Deprecated**: Since 7.3.0. Будет удалено в **VKUI v9**.  Используйте свойство `hoverMode`.                                                                                                                                                                                           |
| `hovered`              | `boolean`                                                                                       | `-`          | Позволяет управлять `hovered`-состоянием извне.                                                                                                                                                                                                                                        |
| `hoverMode`            | `StateModeLiteral`                                                                              | `-`          | Стиль подсветки hover-состояния. Если передать произвольную строку, она добавится как css-класс во время hover.                                                                                                                                                                        |
| `mode`                 | `"primary" \| "secondary" \| "tertiary" \| "outline"`                                           | `primary`    | Стиль отображения кнопки.                                                                                                                                                                                                                                                              |
| `ref`                  | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `render`               | `((props: AllHTMLAttributes<HTMLElement> & Omit<HasRootRef<HTMLElement>, "ref">) => ReactNode)` | `-`          | Позволяет переопределить рендер компонента, получая собранные свойства (включая вычисленные `className` и `style`). Используется вместо `Component`.  Позволяет гибко объединять несколько компонентов без создания промежуточных DOM-узлов и без ремаунта поддерева на каждый рендер. |
| `selected`             | `boolean`                                                                                       | `-`          | Выбранное состояние.                                                                                                                                                                                                                                                                   |
| `size`                 | `"s" \| "m" \| "l"`                                                                             | `m`          | Размер кнопки.                                                                                                                                                                                                                                                                         |
| `textLevel`            | `"1" \| "2" \| "3"`                                                                             | `1`          | Размер шрифта. Этим свойством рекомендуется пользоваться, чтобы отрегулировать размер шрифта у кнопок в `<SubnavigationBar fixed />`.                                                                                                                                                  |
| `unlockParentHover`    | `boolean`                                                                                       | `-`          | Позволяет родительскому компоненту показывать hovered-состояние при наведении на текущий дочерний компонент.  Присваивается дочернему компоненту.                                                                                                                                      |
