Чекбокс

Чекбокс включает или выключает один вариант в форме. Связанные чекбоксы собирают в tk-checkbox-group.

Стабильный

Figma

Обзор

Использование

API

Доступность

Product updates

Events and meetups

Research invitations

<tk-checkbox-group label="Email notifications" helper="Select all that apply">
  <tk-checkbox name="topics" value="product" checked>Product updates</tk-checkbox>
  <tk-checkbox name="topics" value="events">Events and meetups</tk-checkbox>
  <tk-checkbox name="topics" value="research">Research invitations</tk-checkbox>
</tk-checkbox-group>

Анатомия

Часть	Что это
`tk-checkbox`	один вариант и отдельный элемент формы; одна остановка Tab
слот по умолчанию	подпись, обязательна; она же доступное имя, в ней может быть ссылка
квадрат	16px; во включённом виде в нём галочка или минус
подсказка	необязательный текст под подписью
сообщение об ошибке	необязательный текст под подписью, только у одиночного чекбокса
`tk-checkbox-group`	группа; своей остановки Tab не добавляет и сама ничего не отправляет
подпись группы	legend: категория или вопрос, обязательна
подсказка и ошибка группы	под подписью группы, над вариантами
слот группы по умолчанию	элементы `tk-checkbox`, друг под другом

Вся строка, квадрат и подпись, нажимается целиком.

Состояния

Remember me

Product updates

All files

Security alerts

<tk-checkbox>Remember me</tk-checkbox>
<tk-checkbox checked>Product updates</tk-checkbox>
<tk-checkbox indeterminate>All files</tk-checkbox>
<tk-checkbox disabled checked>Security alerts</tk-checkbox>

При наведении у отмеченного квадрата меняется заливка, неотмеченный не меняется. При фокусе с клавиатуры вокруг квадрата появляется рамка.

checked: начальное состояние. Нажатие его переключает; текущее состояние читайте из свойства checked.
indeterminate: родитель, у которого отмечена часть дочерних вариантов. Ставится из вашего кода; нажатие снимает его и переключает checked. Логика «выбрать все» на вашей стороне.
disabled: на чекбокс нельзя перейти, его нельзя изменить, он не отправляется с формой. Отключённые отмеченный и неотмеченный отличаются только бледной галочкой, поэтому если важно, что вариант «включён и закреплён», напишите это текстом. Лучше оставить чекбокс активным.

Обязательность и ошибка

У одиночного чекбокса required значит, что без отметки форма не отправится, и добавляет звёздочку. error показывает ваше сообщение под ним и красную рамку у неотмеченного квадрата.

I agree to the Terms of Service

<tk-checkbox name="terms" required error="Agree to the Terms of Service to continue">
  I agree to the <a href="/terms">Terms of Service</a>
</tk-checkbox>

Чекбокс ничего не проверяет сам. error ставите и снимаете вы. В группе ставьте error на группу, а не на варианты.

Группа

Design

Code

Research

<tk-checkbox-group label="Topics" required error="Select at least one topic">
  <tk-checkbox name="topics" value="design">Design</tk-checkbox>
  <tk-checkbox name="topics" value="code">Code</tk-checkbox>
  <tk-checkbox name="topics" value="research">Research</tk-checkbox>
</tk-checkbox-group>

label обязателен. label-hidden прячет подпись с экрана, но оставляет её для скринридеров.
Ошибка группы стоит над вариантами, поэтому видна и в длинном списке. Квадраты она не перекрашивает.
required только добавляет звёздочку. Проверку «хотя бы один» делайте сами и показывайте результат через error.
disabled отключает все чекбоксы группы.
Каждый чекбокс отправляет свои name и value; у группы значения нет.

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

Группа чекбоксов — чтобы выбрать ни одного, один или несколько независимых вариантов. Выбор применяется, когда форму отправят.
Один чекбокс — для одного «да или нет» в форме, например согласия с условиями.
Если верен ровно один ответ, нужна Radio group.
Если изменение срабатывает сразу, нужен Switch.
Для длинного списка или тесного места берите Multiselect.
Если у варианта есть описание, картинка или цена, берите Selection card.

Текст

Отметка значит «включено»: «Опубликовать магазин», а не «Скрыть магазин».
Подписи короткие, заглавная буква только в начале, без точки в конце.
Согласие пишите от первого лица: «Я принимаю условия использования».
Подпись группы — категория или вопрос, одним предложением.
Подсказка — одно короткое предложение, без точки и без ссылок. Пояснения пишите в ней, а не во всплывающей подсказке.
В ошибке скажите, что сделать, словами подписи: «Выберите хотя бы одну тему». Без «пожалуйста» и «неверно».
Не отмечайте заранее ответы на вопрос. В настройках показывайте текущее значение.
Длинная подпись пусть переносится, не обрезайте её.

Подробнее в Errors.

Можно / нельзя

✅ Можно	❌ Нельзя
Radio group, когда верен только один ответ	Два чекбокса вместо выбора «или — или»
«Опубликовать магазин»	«Скрыть магазин»: с отметкой получается двойное отрицание
Ошибка на группе, над вариантами	`error` на вариантах внутри группы
Независимые варианты	Один чекбокс отмечает или отключает другой
`indeterminate` из кода у родителя	Смешанное состояние как третий вариант для нажатия
Вопросы без отметок	Заранее отмеченный ответ за пользователя

Radio group: выбор ровно одного варианта.
Switch: настройка вкл/выкл, которая срабатывает сразу.
Selection card: карточка вокруг чекбокса для вариантов с подробностями.
Multiselect: много вариантов в выпадающем списке.
Field: подписи и сообщения для текстовых полей; чекбоксу он не нужен.

API

Атрибуты `tk-checkbox`

Атрибут	Тип	По умолчанию	Что делает
`checked`	boolean	`false`	начальное состояние; свойство показывает текущее
`indeterminate`	boolean	`false`	смешанное состояние родителя; ставится из кода
`disabled`	boolean	`false`	не в фокусе, не меняется, не попадает в форму
`required`	boolean	`false`	только одиночный: без отметки форма не отправится; звёздочка
`error`	string		только одиночный: ваше сообщение об ошибке
`helper`	string		подсказка под подписью
`label-hidden`	boolean	`false`	прячет подпись с экрана, доступное имя остаётся
`name`	string		имя поля формы
`value`	string	`on`	отправляется, пока чекбокс отмечен; неотмеченный не отправляет ничего

Атрибуты `tk-checkbox-group`

Атрибут	Тип	По умолчанию	Что делает
`label`	string		подпись группы, обязательна
`label-hidden`	boolean	`false`	прячет подпись с экрана, имя группы остаётся
`helper`	string		подсказка под подписью группы
`error`	string		ошибка группы, над вариантами
`required`	boolean	`false`	добавляет звёздочку; ничего не проверяет
`disabled`	boolean	`false`	отключает все чекбоксы группы

Слоты

Элемент	Слот	Содержимое
`tk-checkbox`	по умолчанию	подпись, обязательна; может содержать ссылки
`tk-checkbox-group`	по умолчанию	элементы `tk-checkbox`

События

tk-checkbox отправляет input и change, когда его переключает пользователь, но не когда checked меняет ваш код. Новое состояние читайте из checked. form.reset() возвращает начальный checked без change. У группы событий нет.

CSS

tk-checkbox::part(row): строка с квадратом и подписью, область нажатия.
tk-checkbox::part(box): нативный чекбокс, нарисованный квадратом.
tk-checkbox-group::part(group): нативный <fieldset>.

Токены

Состояние	Рамка квадрата	Заливка квадрата	Знак	Подпись
не отмечен	`border/subtle`	`surface/default`		`text/default`
отмечен, смешанный	нет	`fill/accent`; при наведении `fill/accent/hover`	`icon/accent/on-fill`	`text/default`
ошибка, не отмечен	`border/error`, 2px	`surface/default`		`text/default`
отключён	`border/disabled`	`surface/disabled`	`icon/disabled`	`text/disabled`

Рамка фокуса border/accent/focus. Подсказки и звёздочка text/secondary, сообщения об ошибке text/error с icon/error. Квадрат 16px, углы radius-4. Значения по темам: Color.

Доступность

Встроено:

Нативный чекбокс внутри <label>: Tab доходит до каждого, Space переключает, нажатие на подпись тоже переключает, формы его видят.
indeterminate озвучивается как смешанное состояние.
Группа — настоящий fieldset, поэтому скринридер называет её подпись вместе с вариантами.
Подсказки и ошибки читаются вместе с чекбоксом или группой. Ошибка начинается со скрытого «Error:», а одиночный чекбокс с error помечен как неверный.
Строка не ниже 24px, рамка фокуса никогда не прячется.

На вашей стороне:

Проверку «хотя бы один» делайте сами и показывайте через error группы. Скринридер не услышит, что группа обязательна, поэтому это передают звёздочка и ваше сообщение.
Если отмечаете поля звёздочкой, объясните её один раз на форму: «* — обязательное поле».
С label-hidden подпись всё равно должна называть вариант, например «Выбрать строку 3».
Держите варианты в одну колонку. Если колонок несколько, проверьте порядок Tab.

Клавиша	Действие
`Tab`	переводит фокус на следующий чекбокс
`Space`	отмечает его или снимает отметку

Пределы контраста

Рамка неотмеченного квадрата: 1.33:1 в светлой теме и 2.00:1 в тёмной, ниже минимума 3:1; в контрастной 4.22:1. При наведении она не меняется.
Отключённый квадрат: отмеченный и неотмеченный отличаются только галочкой: 1.86:1 в светлой теме, 2.91:1 в тёмной и 1.91:1 в контрастной. В тёмной теме у отключённого квадрата нет видимого края.

Анатомия

Состояния

Обязательность и ошибка

Группа

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

Текст

Можно / нельзя

Связанные

API

Атрибуты tk-checkbox

Атрибуты tk-checkbox-group

Слоты

События

CSS

Токены

Доступность

Пределы контраста

Атрибуты `tk-checkbox`

Атрибуты `tk-checkbox-group`