﻿---
description: Компонент для организации контента в виде вкладок.
keywords:
  - TabsItem
---

# Tabs \[tag:component]

Компонент для организации контента в виде вкладок. Позволяет пользователю переключаться между разными разделами информации в одном
пространстве.

```jsx
<Tabs defaultSelectedId="news" layoutFillMode="shrinked">
  <TabsItem before={<Icon24ThumbsUpOutline />} id="recommendations">
    Рекомендации
  </TabsItem>
  <TabsItem id="news" before={<Icon24NewsfeedOutline />}>
    Лента
  </TabsItem>
</Tabs>
```

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

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

* `default` — стандартное отображение вкладок;
* `accent` — акцентный вариант, выделяет активную вкладку;
* `secondary` — более сдержанный стиль для второстепенных разделов.

```jsx
<Tabs defaultSelectedId="news" layoutFillMode="shrinked">
  <TabsItem before={<Icon24UsersOutline />} id="friends">
    Друзья
  </TabsItem>
  <TabsItem id="news" before={<Icon24NewsfeedOutline />}>
    Лента
  </TabsItem>
</Tabs>
<Tabs mode="accent" defaultSelectedId="news" layoutFillMode="shrinked">
  <TabsItem before={<Icon24UsersOutline />} id="friends">
    Друзья
  </TabsItem>
  <TabsItem id="news" before={<Icon24NewsfeedOutline />}>
    Лента
  </TabsItem>
</Tabs>
<Tabs mode="secondary" defaultSelectedId="news" layoutFillMode="shrinked">
  <TabsItem before={<Icon24UsersOutline />} id="friends">
    Друзья
  </TabsItem>
  <TabsItem id="news" before={<Icon24NewsfeedOutline />}>
    Лента
  </TabsItem>
</Tabs>
```

## Распределение вкладок

Задаётся свойством `layoutFillMode`:

* `auto` — автоматическое распределение (по умолчанию):
  * равномерно занимают всю ширину при использовании внутри `HorizontalScroll`;
  * равномерное распределение в режиме `default` на всех платформах кроме VKCOM.
* `stretched` — вкладки растягиваются на всю доступную ширину;
* `shrinked` — вкладки сжимаются по размеру контента.

## Прокрутка к активной вкладке

По умолчанию автоматическая прокрутка к выбранной вкладке отключёна. Для включения:

* `withScrollToSelectedTab` — включает прокрутку к активной вкладке;
* `scrollBehaviorToSelectedTab` — контролирует горизонтальное выравнивание при прокрутке (соответствует параметрам [scrollIntoView](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView)).

### Особенности прокрутки

* Вертикальная прокрутка автоматически отключается, если вкладка находится вне видимой области по вертикали.
* В браузерах без поддержки параметров `scrollIntoView` прокрутка будет отключёна.

## Способы управления активной вкладкой

### Использование `selected` у `TabsItem`

Управлять активной вкладкой можно вручную задавая `selected` у необходимой вкладки:

```jsx
<Tabs>
  <TabsItem>Рекомендации</TabsItem>
  <TabsItem selected>Лента</TabsItem>
</Tabs>
```

### Использование `selectedId`/`defaultSelectedId` у `Tabs`

Также можно управлять активной вкладкой через свойства `selectedId`/`defaultSelectedId` у `Tabs`.
Чтобы этот подход работал, у каждой вкладки `TabsItem` должно быть задано свойство `id`:

```jsx
<Tabs defaultSelectedId="news">
  <TabsItem id="recommendations">Рекомендации</TabsItem>
  <TabsItem id="news">Лента</TabsItem>
</Tabs>
```

```jsx
const [selected, setSelected] = React.useState('news');

<Tabs selectedId={selected} onSelectedIdChange={setSelected}>
  <TabsItem id="recommendations">Рекомендации</TabsItem>
  <TabsItem id="news">Лента</TabsItem>
</Tabs>;
```

## TabsItem \[#tabs-item] \[tag:component]

Элемент вкладки. Автоматически наследует режим отображения (`mode`) от родительского компонента [`Tabs`](/components/tabs).

```jsx
<TabsItem>Фото</TabsItem>
```

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

#### `selected`

Свойство `selected` помечает вкладку выбранной.

```jsx
<TabsItem selected>Фото</TabsItem>
```

#### `disabled`

Свойство `disabled` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

```jsx
<TabsItem disabled>Фото</TabsItem>
```

### Дополнительный контент

Компонент поддерживает различные варианты оформления вкладок:

#### Иконки

* `before` — иконка перед текстом:
  * Для `mode="default"` используйте иконки `24px`;
  * Для других режимов (`accent`, `secondary`) — иконки `20px`.
* `after` — иконка после текста (например, `<Icon16Dropdown />`).

```jsx
<TabsItem before={<Icon24BugOutline />} after={<Icon16Dropdown />}>
  Фото
</TabsItem>
```

#### Статус

Свойство `status` — добавляет элемент для отображения состояния:

* `React.ReactElement` — компонент `Badge` или `Counter` (с `size="s"`).
* `number` — отображает текстовый блок с числом.

```jsx
<TabsItem
  status={
    <Counter mode="primary" appearance="accent-red" size="s">
      12
    </Counter>
  }
>
  Фото
</TabsItem>
```

### Состояния взаимодействия

Компонент поддерживает все стандартные состояния из [`Tappable`](/components/tappable):

* `hoverMode` — стиль при наведении;
* `activeMode` — стиль при активации;
* `focusVisibleMode` — стиль при фокусе.

### Особенности использования

1. Всегда используйте `TabsItem` внутри компонента [`Tabs`](/components/tabs).
2. Для корректной работы доступности (a11y) необходимо:
   * Указать `id` для вкладки
   * Связать с контентом через `aria-controls` (см. документацию [`Tabs`](/components/tabs))

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

Для корректной работы со скринридерами необходимо:

1. В [`TabsItem`](#tabs-item) передать:
   * `id` — уникальный идентификатор вкладки
   * `aria-controls` — указывает на id связанной области контента

2. В области контента указать:
   * `id` — соответствует `aria-controls` вкладки
   * `tabIndex="0"` — делает область фокусируемой
   * `aria-labelledby` — ссылается на id соответствующей вкладки

Пример корректной разметки:

```jsx
<Tabs>
  <TabsItem id="tab1" aria-controls="content1">
    Вкладка 1
  </TabsItem>
  <div id="content1" tabIndex={0} aria-labelledby="tab1">
    Контент 1
  </div>
</Tabs>
```

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

### Tabs

| Свойство                      | Тип                                    | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------- | -------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultSelectedId`           | `string`                               | `-`          | Идентификатор выбранной вкладки по умолчанию. Чтобы свойство работало корректно, у каждого `TabsItem` должно быть прокинуто свойство `id`.                                                                                                                                                                                                      |
| `getRootRef`                  | `Ref<HTMLDivElement>`                  | `-`          |                                                                                                                                                                                                                                                                                                                                                 |
| `layoutFillMode`              | `"auto" \| "stretched" \| "shrinked"`  | `auto`       | При `auto` ширина вкладок определяется контекстом:  - равномерно занимают всю доступную ширину при вложении в `HorizontalScroll`  - равномерно занимают всю доступную ширину при `mode=default` и platform !== 'VKCOM' При `stretched` и `shrinked` вкладки либо равномерно занимают всю ширину, либо выравниваются по контенту соответственно. |
| `mode`                        | `"default" \| "secondary" \| "accent"` | `default`    | Режим отображения компонента.                                                                                                                                                                                                                                                                                                                   |
| `onSelectedIdChange`          | `((id: string) => void)`               | `-`          | Обработчик изменения выбранной вкладки. Чтобы свойство работало корректно, у каждого `TabsItem` должно быть прокинуто свойство `id`.                                                                                                                                                                                                            |
| `ref`                         | `Ref<HTMLDivElement>`                  | `-`          |                                                                                                                                                                                                                                                                                                                                                 |
| `scrollBehaviorToSelectedTab` | `ScrollLogicalPosition`                | `nearest`    | Отвечает за горизонтальное выравнивание при прокрутке до активной вкладки.                                                                                                                                                                                                                                                                      |
| `selectedId`                  | `string`                               | `-`          | Идентификатор выбранной вкладки. Чтобы свойство работало корректно, у каждого `TabsItem` должно быть прокинуто свойство `id`.                                                                                                                                                                                                                   |
| `withScrollToSelectedTab`     | `boolean`                              | `-`          | Включает прокрутку контейнера до активной (`selected`) вкладки.                                                                                                                                                                                                                                                                                 |

### TabsItem

| Свойство           | Тип                                                                     | По умолчанию   | Описание                                                                                                                                                                                                                                                                                                        |
| ------------------ | ----------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activated`        | `boolean`                                                               | `-`            | Позволяет управлять `activated`-состоянием извне.                                                                                                                                                                                                                                                               |
| `activeMode`       | `StateModeLiteral`                                                      | `-`            | Стиль подсветки active-состояния. Если передать произвольную строку, она добавится как css-класс во время active.                                                                                                                                                                                               |
| `after`            | `ReactNode`                                                             | `-`            | Добавляет иконку справа.  Например, `<Icon16Dropdown />`.                                                                                                                                                                                                                                                       |
| `before`           | `ReactNode`                                                             | `-`            | Добавляет иконку слева.  - Для `mode="default"` используйте иконки размером 24. - Для всех остальных `mode` используйте иконки размером 20.                                                                                                                                                                     |
| `Component`        | `ElementType<any, keyof IntrinsicElements>`                             | `-`            |                                                                                                                                                                                                                                                                                                                 |
| `disabled`         | `boolean`                                                               | `-`            | Блокировка взаимодействия с компонентом.                                                                                                                                                                                                                                                                        |
| `focusVisibleMode` | `FocusVisibleMode`                                                      | `inside`       | Стиль аутлайна focus visible. Если передать произвольную строку, она добавится как css-класс при :focus-visible                                                                                                                                                                                                 |
| `getRootRef`       | `Ref<HTMLElement>`                                                      | `-`            |                                                                                                                                                                                                                                                                                                                 |
| `hasActive`        | `boolean`                                                               | `false`        | Указывает, должен ли компонент реагировать на `active`-состояние.                                                                                                                                                                                                                                               |
| `hasHover`         | `boolean`                                                               | `-`            | Указывает, должен ли компонент реагировать на `hover`-состояние.                                                                                                                                                                                                                                                |
| `hovered`          | `boolean`                                                               | `-`            | Позволяет управлять `hovered`-состоянием извне.                                                                                                                                                                                                                                                                 |
| `hoverMode`        | `StateModeLiteral`                                                      | `styles.hover` | Стиль подсветки hover-состояния. Если передать произвольную строку, она добавится как css-класс во время hover.                                                                                                                                                                                                 |
| `ref`              | `Ref<HTMLElement>`                                                      | `-`            |                                                                                                                                                                                                                                                                                                                 |
| `selected`         | `boolean`                                                               | `false`        | Флаг для отображения выбранного состояния.                                                                                                                                                                                                                                                                      |
| `status`           | `number \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | `-`            | Добавляет элемент слева от `after`.  - `React.ReactElement` – либо [`Badge`](https://vkui.io/components/badge) с параметром `mode="prominent"`.   Либо [`Counter`](https://vkui.io/components/counter) с параметрами `mode="prominent" size="s"`. - `number` – для показа текстового блока с переданным числом. |
