---
description: Компонент, который позволяет пользователю выбрать один или несколько вариантов из списка опций.
tags: selection
---

<Overview group="forms">

# Checkbox [tag:component]

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

</Overview>

{/* @example-description: Базовый чекбокс с текстовой подписью. */}
<Playground>
  ```jsx
  <Checkbox name="notifications">Уведомления включены</Checkbox>
  ```
</Playground>

## Применение компонента

- если вы используете компонент `Checkbox` для глобального управления состоянием другой группы компонентов `Checkbox`, используйте
  свойство `indeterminate` для индикации разного состояния дочерних переключателей;
- если вам необходим компонент, который предоставляет выбор более чем из двух взаимоисключающих значений,
  используйте группу компонентов [`Radio`](/components/radio).

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

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
React-компонентов, прочитать про это можно в [документации React](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable).

Для использования неконтролируемого режима достаточно просто _не_ передавать `checked` или передавать `defaultChecked`, если
требуется задать значение по умолчанию.
Для контролируемого режима используйте связку свойств `checked`/`onChange` для задания значения и его изменения.

Есть возможность также влиять на значение "не определено". В неконтролируемом режиме передавайте свойство `defaultIndeterminate`,
в контролируемом используйте свойство `indeterminate`. Получить значение "не определено" в `onChange` нельзя.

```jsx
// Неконтролируемое состояние, по умолчанию в состоянии "выбран"
<Checkbox defaultChecked />

// Неконтролируемое состояние, по умолчанию в состоянии "не определено"
<Checkbox defaultIndeterminate />

// Контролируемое состояние, значение "не выбран"
const [checked, setChecked] = React.useState(false);

<Checkbox checked={checked} onChange={(event) => setChecked(event.target.checked)} />;
```

## Состояния

### `disabled`

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

{/* @example-description: Чекбокс в неактивном состоянии с `disabled`. */}
<Playground>
  ```jsx
  <Checkbox name="notifications" disabled>
    Уведомления включены
  </Checkbox>
  ```
</Playground>

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

По умолчанию компонент использует для визуализации два набора (для `"regular"` и `"compact"` режима) стандартных иконок,
включающих три состояния. С помощью представленных ниже свойств вы можете определить собственные наборы иконок:

- `IconIndeterminate` - иконка для неопределенного состояния;
- `IconOffCompact` - иконка для не выбранного состояния в режиме `"compact"` (планшеты, десктоп);
- `IconOffRegular` - иконка для не выбранного состояния в режиме `"regular"` (мобильные устройства);
- `IconOnCompact` - иконка для выбранного состояния в режиме `"compact"` (планшеты, десктоп);
- `IconOnRegular` - иконка для выбранного состояния в режиме `"regular"` (мобильные устройства).

Рекомендуется использовать иконки размером `24px` для режима `"regular"` и `20px` для режима `"compact"`.

{/* @example-description: Кастомный набор иконок для состояний чекбокса в `compact` и `regular` режимах. */}
<Playground>
  ```jsx
  <Checkbox
    IconOffCompact={Icon20LikeOutline}
    IconOffRegular={Icon24LikeOutline}
    IconOnCompact={Icon20Like}
    IconOnRegular={Icon24Like}
  >
    Пицца с ананасами
  </Checkbox>
  ```
</Playground>

## Кастомизация

Компонент поддерживает свойство `slotProps`, которое даёт возможность прокинуть свойство в некоторые внутренние элементы.

Это удобно для добавления кастомных классов, data-атрибутов, aria-атрибутов, обработчиков событий, доступов к элементам через `getRootRef` и других расширений, не влияя на внешний API компонента.

{/* @example-description: Пример `slotProps` для настройки корня и внутреннего `input` чекбокса. */}
<Playground>
  ```jsx
  const inputRef = React.useRef();

  return (
    <Checkbox
      defaultChecked={false}
      className="my-root-class"
      data-testid="checkbox-root"
      id="checkbox-input-id"
      slotProps={{
        root: {
          id: 'checkbox-root-id',
        },
        input: {
          className: 'my-input-class',
          'aria-label': 'checkbox',
          getRootRef: inputRef,
        },
      }}
    >
      Уведомления включены
    </Checkbox>
  )
  ```
</Playground>

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

Компонент `Checkbox` обеспечивает базовую доступность, используя нативные `HTML`-элементы `input[type="checkbox"]` и `label`.

Для улучшения доступности рекомендуется предавать в компонент атрибуты `aria-labelledby`, `aria-label` и `aria-describedby`
для предоставления дополнительной информации об элементе.

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

### Checkbox

| Свойство | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `activeMode` | `StateModeLiteral` | `-` | Стиль подсветки active-состояния. Если передать произвольную строку, она добавится как css-класс во время active. |
| `defaultIndeterminate` | `boolean` | `-` | Неопределенное состояние чекбокса по умолчанию. |
| `description` | `ReactNode` | `-` | Подпись под основным текстом. |
| `focusVisibleMode` | `FocusVisibleMode` | `-` | Стиль аутлайна focus visible. Если передать произвольную строку, она добавится как css-класс при :focus-visible |
| `getRef` | `Ref<HTMLInputElement>` | `-` | **Deprecated**: Since 7.9.0. Вместо этого используйте `slotProps={ input: { getRootRef: ... } }`. |
| `getRootRef` | `Ref<HTMLLabelElement>` | `-` |  |
| `hasActive` | `boolean` | `-` | Указывает, должен ли компонент реагировать на `active`-состояние. |
| `hasHover` | `boolean` | `-` | Указывает, должен ли компонент реагировать на `hover`-состояние. |
| `hoverMode` | `StateModeLiteral` | `-` | Стиль подсветки hover-состояния. Если передать произвольную строку, она добавится как css-класс во время hover. |
| `IconIndeterminate` | `CheckboxInputIconType` | `-` | Иконка для неопределенного состояния. |
| `IconOffCompact` | `CheckboxInputIconType` | `-` | Иконка для выключенного состояния в компактном режиме. |
| `IconOffRegular` | `CheckboxInputIconType` | `-` | Иконка для выключенного состояния в обычном режиме. |
| `IconOnCompact` | `CheckboxInputIconType` | `-` | Иконка для включенного состояния в компактном режиме. |
| `IconOnRegular` | `CheckboxInputIconType` | `-` | Иконка для включенного состояния в обычном режиме. |
| `indeterminate` | `boolean` | `-` | Неопределенное состояние чекбокса. |
| `noPadding` | `boolean` | `-` | Отключает отступы у чекбокса. При использовании этого свойства, значение по умолчанию для свойств `hoverMode` и `activeMode` становится `"opacity"`. |
| `slotProps` | `{ root?: (Omit<LabelHTMLAttributes<HTMLLabelElement>, "children"> & HasRootRef<HTMLLabelElement> & HasDataAttribute); input?: (ClassAttributes<...> & ... 2 more ... & HasDataAttribute) \| undefined; } \| undefined` | `-` | Свойства, которые можно прокинуть внутрь компонента: - `root`: свойства для прокидывания в корень компонента; - `input`: свойства для прокидывания в скрытый `input`. |
| `titleAfter` | `ReactNode` | `-` | Контент, идущий за основным текстом. |

### Checkbox.Input

| Свойство | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `defaultIndeterminate` | `boolean` | `-` | Неопределенное состояние чекбокса по умолчанию. |
| `getRef` | `Ref<HTMLInputElement>` | `-` | **Deprecated**: Since 7.9.0. Вместо этого используйте `slotProps={ input: { getRootRef: ... } }`. |
| `getRootRef` | `Ref<HTMLDivElement>` | `-` |  |
| `IconIndeterminate` | `CheckboxInputIconType` | `-` | Иконка для неопределенного состояния. |
| `IconOffCompact` | `CheckboxInputIconType` | `-` | Иконка для выключенного состояния в компактном режиме. |
| `IconOffRegular` | `CheckboxInputIconType` | `-` | Иконка для выключенного состояния в обычном режиме. |
| `IconOnCompact` | `CheckboxInputIconType` | `-` | Иконка для включенного состояния в компактном режиме. |
| `IconOnRegular` | `CheckboxInputIconType` | `-` | Иконка для включенного состояния в обычном режиме. |
| `indeterminate` | `boolean` | `-` | Неопределенное состояние чекбокса. |
| `slotProps` | `{ root?: (Omit<HTMLAttributes<HTMLDivElement>, "children"> & HasRootRef<HTMLDivElement> & HasDataAttribute); input?: (ClassAttributes<...> & ... 2 more ... & HasDataAttribute) \| undefined; } \| undefined` | `-` | Свойства, которые можно прокинуть внутрь компонента: - `root`: свойства для прокидывания в корень компонента; - `input`: свойства для прокидывания в скрытый `input`. |