Radio
Adapter React independente em que Ark UI fornece as parts e Zag mantém seleção exclusiva, roving focus, teclado e formulário.
Design
Preview funcional
Executado pelo adapter independente Ark UI com comportamento Zag.
Carregando preview funcional…
Anatomia
1 Label (
2 Input (
3 Dot — pseudo-elemento CSS, visível quando selecionado.
4 Grupo (
5 Legend (
.ds-radio-label) — envolve radio + texto, estende área de clique.2 Input (
.ds-radio) — <input type="radio"> nativo estilizado.3 Dot — pseudo-elemento CSS, visível quando selecionado.
4 Grupo (
.ds-radio-group) — <fieldset> envolvendo radios relacionados.5 Legend (
.ds-radio-group__legend) — título do grupo, fornece contexto para leitores de tela.
Grupo de Radio
Tamanhos
Grupo com erro
Desabilitado
Estados
| State | CSS trigger | Visual change | Token |
|---|---|---|---|
| Unselected | --- | Neutral control fill and border | component.radio.control.fill.unselected.default, component.radio.control.border-color.unselected.default |
| Unselected hover | :hover | Darker neutral control border/fill | component.radio.control.fill.unselected.hover, component.radio.control.border-color.unselected.hover |
| Selected | :checked | Primary control fill with dot | component.radio.control.fill.selected.default, component.radio.dot.fill.selected.default |
| Selected hover | :checked:hover | Darker primary control fill | component.radio.control.fill.selected.hover, component.radio.dot.fill.selected.hover |
| Focus | :focus-visible | 2px outline ring | component.radio.focus-ring.radius.default + component.focus-ring.* |
| Error group | .ds-radio-group--error | Error border on controls and message below group | component.radio.control.border-color.unselected.error, semantic.feedback.error.content-default |
| Disabled | [disabled] | Muted control, dot and label | component.radio.control.fill.*.disabled, semantic.content.disabled |
Propriedades Figma
| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
Show Label | Boolean | true | Exibe ou oculta o label do controle |
Label | Text | "Rótulo" | Texto do label (label/md) |
Show Description | Boolean | false | Exibe texto descritivo abaixo do label |
Description | Text | "Texto descritivo" | Texto multiline de descrição (body/sm) |
Show Helper Text | Boolean | false | Exibe texto auxiliar abaixo da description |
Helper Text | Text | "Texto auxiliar" | Anotação em caption/sm (content/secondary) |
Uso
Quando usar
- Exatamente uma opção deve ser escolhida entre duas a sete alternativas visíveis.
- Comparar as alternativas antes de escolher ajuda a tomar a decisão.
Quando não usar
- Zero, uma ou várias opções podem ser escolhidas; use Checkbox.
- Há muitas alternativas ou pouco espaço; use Select.
Quando escolher esta saída
Adote este adapter em projetos que escolheram Ark UI e Zag como arquitetura comportamental. Não o importe dentro da saída shadcn/Base UI.
Implementação
- Status
- Beta
- Distribuição
- Adapter de source
Source do adapter
packages/react/src/ark/radio.jsx
import {
RadioGroup,
RadioGroupContent,
RadioGroupHiddenInput,
RadioGroupItem,
RadioGroupLabel,
RadioGroupLegend,
RadioGroupOption,
} from '@tis/react/ark/radio'Acessibilidade
Interação por teclado
| Tecla | Ação |
|---|---|
Tab | Move o foco para dentro do grupo de radio (tab stop único) ou para fora |
Arrow Up / Arrow Left | Seleciona a opção anterior no grupo |
Arrow Down / Arrow Right | Seleciona a próxima opção no grupo |
Um grupo de radio se comporta como um tab stop único. Teclas de seta navegam entre opções dentro do grupo, e a seleção se move com o foco.
Accessibility
| Critério WCAG | Requisito | Status |
|---|---|---|
| 1.3.1 Info and Relationships (A) | Grupo em <fieldset> + <legend> | ✓ |
| 2.4.11 Focus Appearance (AA) | Focus ring visível via :focus-visible | ✓ |
| 2.5.8 Target Size min (AA) | Label estende a área de clique além do radio | ✓ |
| 4.1.2 Name, Role, Value (A) | <input type="radio"> nativo fornece role + estado automaticamente | ✓ |
| 3.3.1 Error Identification (A) | Erro do grupo comunicado via ds-radio-group--error | ✓ |
Notas de implementação
Sempre envolva grupos de radio em um <fieldset> com um <legend> para fornecer contexto de grupo aos leitores de tela. Usa <input type="radio"> nativo para navegação por teclado integrada -- teclas de seta movem entre opções dentro de um grupo, Tab entra e sai do grupo. Focus ring é visível no foco por teclado via :focus-visible.
Label invisível — exige ARIA explícito
Quando Show Label = false e Show Description = true, vincule o <input> à descrição via aria-labelledby="id-da-description". Se nenhum dos dois estiver visível, use aria-label diretamente no <input>. O Helper Text deve sempre ser vinculado via aria-describedby="id-do-helper".
Responsabilidade da saída
Preserve a semântica Ark/Zag e valide seleção exclusiva, navegação por setas, Space, estados disabled e invalid, foco visível e envio dos hidden inputs no formulário.
Evidência de validação
Coberta pelo Storybook da saída independente e por verificações de browser, responsividade, teclado, Axe e bundle.