Радиогруппа
Радиогруппа просит выбрать ровно один ответ из короткого списка. tk-radio-group хранит подпись и значение, каждый tk-radio — один вариант.
<tk-radio-group label="How should we contact you?" name="contact" required> <tk-radio value="email">Email</tk-radio> <tk-radio value="phone" helper="Weekdays, 9:00 to 17:00">Phone call</tk-radio> <tk-radio value="none">Don't contact me</tk-radio> </tk-radio-group>
Анатомия
| Часть | Что это |
|---|---|
tk-radio-group |
группа и поле формы; одна остановка Tab на все варианты |
| подпись группы | legend: обычно сам вопрос, обязательна |
| подсказка и ошибка группы | под подписью группы, над вариантами |
| слот группы по умолчанию | элементы tk-radio, друг под другом |
tk-radio |
один вариант; работает только внутри группы |
| кружок | 20px; у выбранного — заливка и точка |
| слот по умолчанию | подпись варианта, обязательна; она же доступное имя варианта |
| подсказка | необязательный текст под подписью варианта |
Вся строка, кружок и подпись, нажимается целиком.
Значение
value группы — это value выбранного варианта. Чтобы вариант был выбран заранее,
задайте value группе; пустое значение значит, что ничего не выбрано.
<tk-radio-group label="Theme" name="theme" value="system"> <tk-radio value="light">Light</tk-radio> <tk-radio value="dark">Dark</tk-radio> <tk-radio value="system">Match the system</tk-radio> </tk-radio-group>
name,value,requiredиerrorставьте на группу, а не на вариант.- В вопросах ничего не выбирайте заранее. В настройках показывайте текущее значение.
- Группа отправляет одну пару
nameиvalue; если ничего не выбрано, не отправляет ничего.
Состояния
<tk-radio-group label="Delivery" name="delivery" value="standard"> <tk-radio value="standard">Standard</tk-radio> <tk-radio value="express" helper="Not available for this address" disabled>Express</tk-radio> </tk-radio-group>
При наведении у выбранного кружка меняется заливка, невыбранный не меняется. При фокусе с клавиатуры вокруг кружка появляется рамка.
disabledна варианте: вариант серый, стрелки его пропускают. Объясните причину в подсказке или уберите вариант.disabledна группе: отключает все варианты и убирает остановку Tab. Отключённые выбранный и невыбранный кружки отличаются только бледной точкой, поэтому если важен закреплённый выбор, напишите о нём текстом.
Обязательность и ошибка
<tk-radio-group label="Plan" name="plan" required error="Select a plan"> <tk-radio value="free">Free</tk-radio> <tk-radio value="team">Team</tk-radio> </tk-radio-group>
requiredне даёт отправить форму, пока вариант не выбран, и добавляет звёздочку.errorпоказывает ваше сообщение над вариантами, поэтому оно видно и в длинном списке. Кружки оно не перекрашивает.- Группа ничего не проверяет сама.
errorставите и снимаете вы.
Когда использовать
- Радиогруппа — когда верен ровно один из 2–6 коротких вариантов. Выбор применяется, когда форму отправят.
- Если верных ответов может быть несколько, нужна
Checkbox group . - Если вариантов больше шести или места мало, берите
Select . - Чтобы сразу переключить вид, берите
Segmented control . Стрелки выбирают вариант на ходу, поэтому радиогруппа никогда не должна срабатывать сама. - Для одной настройки вкл/выкл нужен
Switch , а не две радиокнопки. - Если у варианта есть описание, картинка или цена, берите
Selection card .
Снять выбор в радиогруппе нельзя, можно только выбрать другой вариант. Если «ничего» — нормальный ответ, добавьте его вариантом, например «Ничего из перечисленного».
Текст
- Подпись группы — это вопрос, одним предложением, заглавная буква только в начале.
- Подписи вариантов короткие, с заглавной только в начале, без точки в конце. Каждая говорит, что значит этот выбор.
- Подсказка — одно короткое предложение, без точки и без ссылок.
- Ошибку пишите как «Выберите» и что именно, словами подписи: «Выберите тариф». Для вопроса «да или нет»: «Выберите „да“, если у вас бизнес-аккаунт». Без «пожалуйста» и «неверно».
- Располагайте варианты логично, по умолчанию по алфавиту. Порядок по популярности подталкивает к одному ответу.
- Длинная подпись пусть переносится, не обрезайте её.
Подробнее в
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Группа чекбоксов, когда подходят несколько ответов | Заставлять выбрать один ответ радиокнопками |
| Применять выбор при отправке формы | Срабатывать на выбор, пока двигаются стрелки |
value на группе |
checked на варианте |
| 2–6 коротких вариантов друг под другом | 10 вариантов радиокнопками; берите Select |
| «Ничего из перечисленного» отдельным вариантом | Рассчитывать, что выбор снимут |
| Объяснить отключённый вариант или убрать его | Отключать вариант без причины |
Связанные
Checkbox : ни одного, один или несколько вариантов.Segmented control : один выбор, который сразу переключает вид.Select : один вариант из длинного списка.Selection card : карточка вокруг радиокнопки для вариантов с подробностями.Switch : настройка вкл/выкл, которая срабатывает сразу.
API
Атрибуты tk-radio-group
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
label |
string | подпись группы, обязательна | |
label-hidden |
boolean | false |
прячет подпись с экрана, имя группы остаётся |
name |
string | имя поля формы, обязательно | |
value |
string | '' |
value выбранного варианта; пусто, если ничего не выбрано |
helper |
string | подсказка под подписью группы | |
error |
string | ошибка группы, над вариантами | |
required |
boolean | false |
форма не отправится без выбора; звёздочка |
disabled |
boolean | false |
отключает все варианты и убирает остановку Tab |
Атрибуты tk-radio
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
value |
string | '' |
отправляемое значение, обязательно; уникально в группе |
helper |
string | подсказка под подписью варианта | |
disabled |
boolean | false |
вариант серый, стрелки его пропускают |
checked |
boolean | false |
только для чтения, его ставит группа. Задавайте value группы |
Слоты
| Элемент | Слот | Содержимое |
|---|---|---|
tk-radio-group |
по умолчанию | элементы tk-radio |
tk-radio |
по умолчанию | подпись варианта, обязательна |
События
tk-radio-group отправляет change, когда вариант выбирает пользователь, в том числе
стрелками, но не когда value меняет ваш код. Выбор читайте из value. form.reset()
возвращает начальный value без change. У tk-radio событий нет.
Методы
tk-radio-group.focus() переводит фокус на выбранный вариант или на первый доступный.
CSS
tk-radio-group::part(group): нативный<fieldset>.tk-radio::part(row): строка с кружком и подписью, область нажатия.
Токены
| Состояние | Рамка кружка | Заливка кружка | Точка | Подпись |
|---|---|---|---|---|
| не выбран | border/subtle |
surface/default |
text/default |
|
| выбран | нет | fill/accent; при наведении fill/accent/hover |
icon/accent/on-fill |
text/default |
| отключён | border/disabled |
surface/disabled |
icon/disabled |
text/disabled |
Рамка фокуса border/accent/focus. Подсказки и звёздочка text/secondary, ошибки
text/error с icon/error. Кружок 20px, radius-full; точка 8px. Значения по темам:
Доступность
Встроено:
- Скринридер называет группу радиогруппой, читает её подпись и число вариантов.
- Клавиатура как у нативных радиокнопок: одна остановка Tab на группу, стрелки переносят фокус и выбор, отключённые варианты пропускаются.
requiredиerrorозвучиваются на группе. Ошибка начинается со скрытого «Error:».- Подсказки и ошибки читаются вместе с вариантом или группой.
- Строка не ниже 24px, рамка фокуса никогда не прячется.
На вашей стороне:
- Ничего не делайте по выбору, пока форму не отправили.
- Добавьте «Ничего из перечисленного», если это нормальный ответ: снять выбор нельзя.
- Если отмечаете поля звёздочкой, объясните её один раз на форму: «* — обязательное поле».
- Держите варианты в одну колонку.
| Клавиша | Действие |
|---|---|
Tab |
переводит фокус в группу, на выбранный или первый вариант, и из неё |
↓ / → |
выбирает следующий вариант, после последнего — первый |
↑ / ← |
выбирает предыдущий вариант, после первого — последний |
Space |
выбирает вариант в фокусе |
Пределы контраста
- Рамка невыбранного кружка: 1.33:1 в светлой теме и 2.00:1 в тёмной, ниже минимума 3:1; в контрастной 4.22:1. При наведении она не меняется.
- Отключённый кружок: выбранный и невыбранный отличаются только точкой: 1.86:1 в светлой теме, 4.09:1 в тёмной и 1.91:1 в контрастной.