﻿---
description: Кнопки, которые используются для вызова инструмента, вставки вложений или для форматирования.
---

# ToolButton \[tag:component]

Кнопки, которые используются для вызова инструмента, вставки вложений или для форматирования.
Их можно использовать как кнопки для разового действия или для включения/выключения режима.

Компонент наследует свойства компонента [`Tappable`](/components/tappable),
что обеспечивает базовую функциональность для интерактивных элементов, таких как обработка событий нажатия (`onClick`),
отключение (`disabled`) и поддержка ссылок (`href`)

```jsx
<Box>
  <ToolButton IconCompact={Icon20Add} IconRegular={Icon24Add} aria-label="Добавить вложение" />
</Box>
```

```jsx
<ToolButton IconCompact={Icon20Add} IconRegular={Icon24Add} aria-label="Добавить вложение" />
```

## Обязательные свойства

### Адаптивные иконки

Обязательные свойства `IconCompact` и `IconRegular` позволяют использовать разные иконки в зависимости от режима отображения
(см. [Адаптивность | Размеры элементов интерфейса](/overview/adaptivity#density)). Это помогает поддерживать доступность и удобство использования
на различных устройствах.

## Контент

Внутри кнопки допускается разместить дочерний элемент (`children`) — текст, который будет отображаться.
За расположение контента отвечает свойство `direction`:

* `row` — иконка и текст идут горизонтально, рядом (по умолчанию);
* `column` — иконка над текстом, вертикально.

```jsx
<ToolButton IconCompact={Icon20Add} IconRegular={Icon24Add} direction="row">
  row
</ToolButton>
<ToolButton IconCompact={Icon20Add} IconRegular={Icon24Add} direction="column">
  column
</ToolButton>
```

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

Устанавливаются через свойство `mode`:

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

## Визуальное оформление

### Цвет

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

#### `"accent"`

Значение задаёт кнопке акцентный цвет, который может меняться в зависимости от светлой или тёмной схемы.

```jsx
<ToolButton appearance="accent" mode="primary" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Primary
</ToolButton>
<ToolButton appearance="accent" mode="secondary" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Secondary
</ToolButton>
<ToolButton appearance="accent" mode="tertiary" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Tertiary
</ToolButton>
<ToolButton appearance="accent" mode="outline" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Outline
</ToolButton>
```

#### `"neutral"`

Значение задаёт кнопке нейтральный цвет, который также может являться альтернативным акцентным цветом кнопки.

```jsx
<ToolButton appearance="neutral" mode="primary" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Primary
</ToolButton>
<ToolButton appearance="neutral" mode="secondary" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Secondary
</ToolButton>
<ToolButton appearance="neutral" mode="tertiary" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Tertiary
</ToolButton>
<ToolButton appearance="neutral" mode="outline" IconCompact={Icon20Add} IconRegular={Icon24Add}>
  Outline
</ToolButton>
```

### Скругление

Управляется свойством `rounded`:

* Если `true` — кнопка становится круглой (50% скругление);
* Не работает, если `direction="column"` и есть дочерние элементы (`children`).

```jsx
<ToolButton
  IconCompact={Icon20Add}
  IconRegular={Icon24Add}
  aria-label="Добавить вложение"
  rounded
/>
```

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

Компонент `ToolButton` автоматически выбирает правильный HTML-тег: по умолчанию это `button`,
а если передано свойство `href`, то `a`. Это обеспечивает базовую поддержку доступности.

Компонент поддерживает все стандартные `aria`-атрибуты, что позволяет переопределить поведение по умолчанию,
если это необходимо.

> Если одновременно переданы свойства `href` и `disabled`, компонент отключает `href`,
> чтобы соответствовать требованиям доступности. По возможности избегайте такой комбинации.

### Кнопки с иконками

Если `ToolButton` содержит только иконку (без текста), обязательно добавьте `aria-label` с описанием действия кнопки.
Это поможет пользователям с ограниченными возможностями понять назначение кнопки.

```jsx
<ToolButton
  IconRegular={Icon24Add}
  IconCompact={Icon20Add}
  mode="primary"
  appearance="accent"
  aria-label="Добавить вложение"
/>
```

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

| Свойство               | Тип                                                                                             | По умолчанию | Описание                                                                                                                                                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activated`            | `boolean`                                                                                       | `-`          | Позволяет управлять `activated`-состоянием извне.                                                                                                                                                                                                                                      |
| `activeClassName`      | `string`                                                                                        | `-`          | **Deprecated**: Since 7.3.0. Будет удалено в **VKUI v9**.  Используйте свойство `activeMode`.                                                                                                                                                                                          |
| `activeEffectDelay`    | `number`                                                                                        | `-`          | Длительность показа `active`-состояния.                                                                                                                                                                                                                                                |
| `activeMode`           | `StateModeLiteral`                                                                              | `-`          | Стиль подсветки active-состояния. Если передать произвольную строку, она добавится как css-класс во время active.                                                                                                                                                                      |
| `appearance`           | `"accent" \| "neutral"`                                                                         | `accent`     | Внешний вид компонента.                                                                                                                                                                                                                                                                |
| `borderRadiusMode`     | `"auto" \| "inherit"`                                                                           | `-`          | Задает border-radius элементу В режиме `auto` на маленьких экранах `border-radius: 0`, иначе определяется токеном `--vkui--size_border_radius--regular`.                                                                                                                               |
| `Component`            | `ElementType<any, keyof IntrinsicElements>`                                                     | `-`          |                                                                                                                                                                                                                                                                                        |
| `direction`            | `"row" \| "column"`                                                                             | `row`        | Направление контента.                                                                                                                                                                                                                                                                  |
| `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.                                                                                                                                                                        |
| `**IconCompact** \*`   | `ComponentType<{ className?: string; }>`                                                        | `-`          | Компонент иконки для компактного размера.                                                                                                                                                                                                                                              |
| `**IconRegular** \*`   | `ComponentType<{ className?: string; }>`                                                        | `-`          | Компонент иконки для обычного размера.                                                                                                                                                                                                                                                 |
| `mode`                 | `"primary" \| "secondary" \| "tertiary" \| "outline"`                                           | `primary`    | Режим отображения компонента.                                                                                                                                                                                                                                                          |
| `ref`                  | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `render`               | `((props: AllHTMLAttributes<HTMLElement> & Omit<HasRootRef<HTMLElement>, "ref">) => ReactNode)` | `-`          | Позволяет переопределить рендер компонента, получая собранные свойства (включая вычисленные `className` и `style`). Используется вместо `Component`.  Позволяет гибко объединять несколько компонентов без создания промежуточных DOM-узлов и без ремаунта поддерева на каждый рендер. |
| `rounded`              | `boolean`                                                                                       | `-`          | Задаёт `50%` закругления для контейнера.  > Note: игнорируется при `direction="column"` если передан `children`.                                                                                                                                                                       |
| `unlockParentHover`    | `boolean`                                                                                       | `-`          | Позволяет родительскому компоненту показывать hovered-состояние при наведении на текущий дочерний компонент.  Присваивается дочернему компоненту.                                                                                                                                      |
