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

# Checkbox \[tag:component]

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

```jsx
<Checkbox name="notifications">Уведомления включены</Checkbox>
```

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

* если вы используете компонент `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` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

```jsx
<Checkbox name="notifications" disabled>
  Уведомления включены
</Checkbox>
```

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

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

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

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

```jsx
<Checkbox
  IconOffCompact={Icon20LikeOutline}
  IconOffRegular={Icon24LikeOutline}
  IconOnCompact={Icon20Like}
  IconOnRegular={Icon24Like}
>
  Пицца с ананасами
</Checkbox>
```

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

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

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

```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>
)
```

## Доступность (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"`.                  |
| `ref`                  | `Ref<HTMLLabelElement>`                                                                                                                                                                                                 | `-`          |                                                                                                                                                                       |
| `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`                                                                                                                                                                                                      | `-`          | Неопределенное состояние чекбокса.                                                                                                                                    |
| `ref`                  | `Ref<HTMLDivElement>`                                                                                                                                                                                          | `-`          |                                                                                                                                                                       |
| `slotProps`            | `{ root?: (Omit<HTMLAttributes<HTMLDivElement>, "children"> & HasRootRef<HTMLDivElement> & HasDataAttribute); input?: (ClassAttributes<...> & ... 2 more ... & HasDataAttribute) \| undefined; } \| undefined` | `-`          | Свойства, которые можно прокинуть внутрь компонента: - `root`: свойства для прокидывания в корень компонента; - `input`: свойства для прокидывания в скрытый `input`. |
