Radio
Radio buttons permitem que usuários selecionem exatamente uma opção de um grupo. Construído com <input type="radio"> nativo dentro de um <fieldset>.Radio buttons let users select exactly one option from a group. Built with native <input type="radio"> inside a <fieldset>.
Quando usarWhen to use
Use radio buttons quandoUse radio buttons when
Exatamente uma opção deve ser selecionada de 2-7 opções visíveis. Radio buttons tornam todas as opções visíveis de uma vez, ajudando usuários a comparar escolhas.Exactly one option must be selected from 2-7 visible options. Radio buttons make all options visible at once, helping users compare choices.
Não use radio buttons quandoDon't use radio buttons when
Múltiplas seleções são necessárias (use Checkbox), há mais de 7 opções (use Select), ou para liga/desliga binário com efeito imediato (use Toggle).Multiple selections are needed (use Checkbox), there are more than 7 options (use Select), or for a binary on/off with immediate effect (use Toggle).
AnatomiaAnatomy
4
5
1
2
3
1 Label (
2 Input (
3 Dot — pseudo-elemento CSS, visível quando selecionado.
4 Grupo (
5 Legend (
2 Input (
3 Dot — CSS pseudo-element, visible when selected.
4 Group (
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.1 Label (.ds-radio-label) — wraps radio + text, extends click target.2 Input (
.ds-radio) — styled native <input type="radio">.3 Dot — CSS pseudo-element, visible when selected.
4 Group (
.ds-radio-group) — <fieldset> wrapping related radios.5 Legend (
.ds-radio-group__legend) — group heading, provides context to screen readers.
Grupo de RadioRadio Group
<fieldset class="ds-radio-group">
<legend class="ds-radio-group__legend">Notification preference</legend>
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="notify" value="email" checked>
Email
</label>
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="notify" value="sms">
SMS
</label>
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="notify" value="push">
Push notification
</label>
</fieldset>TamanhosSizes
<label class="ds-radio-label">
<input type="radio" class="ds-radio ds-radio--sm" name="size">
Small (16px)
</label>
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="size">
Medium (20px, default)
</label>
<label class="ds-radio-label">
<input type="radio" class="ds-radio ds-radio--lg" name="size">
Large (24px)
</label>Grupo com erroError Group
<fieldset class="ds-radio-group ds-radio-group--error">
<legend class="ds-radio-group__legend">Select a plan</legend>
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="plan" value="free">
Free
</label>
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="plan" value="pro">
Pro
</label>
<span class="ds-radio-group__error">Please select a plan to continue.</span>
</fieldset>DesabilitadoDisabled
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="disabled-demo" disabled>
Disabled unchecked
</label>
<label class="ds-radio-label">
<input type="radio" class="ds-radio" name="disabled-demo2" checked disabled>
Disabled checked
</label>Boas práticasBest practices
Faça
Sempre envolva em
<fieldset> com <legend>. Use 2-7 opções visíveis.Always wrap in <fieldset> with <legend>. Use 2-7 visible options.Não faça
Usar um radio button sozinho. Para uma escolha binária, use Checkbox.Use a single radio button alone. For a single binary choice, use a Checkbox instead.
Faça
Nenhuma opção pré-selecionada a menos que um padrão genuinamente sensato exista.No option pre-selected unless a genuinely sensible default exists.
Não faça
Pré-selecionar uma opção a menos que seja genuinamente a mais comum ou o padrão sensato.Pre-select an option unless it is genuinely the most common or sensible default.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| Use labels paralelosUse parallel labels | "Free plan", "Pro plan", "Enterprise plan" — not "Free", "The pro one", "Enterprise tier" |
| A legend deve ser uma pergunta claraLegend should be a clear question | "Select a plan" — not "Plans" |
| Mantenha opções curtas (1-4 palavras)Keep options short (1-4 words) | "Monthly" — not "Bill me on a monthly basis" |
| Use sentence caseUse sentence case | "Push notification" — not "Push Notification" |
Mapeamento de tokensToken mapping
Mesmos tokens do Checkbox exceto border-radius: 50% (círculo) em vez de foundation.radius.4.Same tokens as Checkbox except border-radius: 50% (circle) instead of foundation.radius.4.
| PropriedadeProperty | Token (semantic) | Variável CSSCSS variable |
|---|---|---|
| border (unselected) | semantic.border.control-default | --ds-border-control-default |
| background (selected) | semantic.primary.background.default | --ds-primary-background-default |
| dot color | semantic.primary.content-default | --ds-primary-content-default |
| border (error) | semantic.feedback.error.border-default | --ds-feedback-error-border-default |
| focus ring | semantic.focus.ring.* | --ds-focus-ring-width, --ds-focus-ring-offset, --ds-focus-ring-color |
| border-radius | 50% (circle) | border-radius: 50% |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-radio | Radio button nativo estilizadoCustom styled native radio button |
ds-radio-label | Wrapper do label (envolve radio + texto)Label wrapper (wraps radio + text) |
ds-radio-group | Container fieldset para um grupo de radiosFieldset container for a group of radios |
ds-radio-group__legend | Legend/título do grupoGroup legend/heading |
ds-radio--sm | Tamanho pequeno (16px)Small size (16px) |
ds-radio--lg | Tamanho grande (24px)Large size (24px) |
ds-radio-group--error | Estado de erro para o grupoError state for the group |
ds-radio-group__error | Texto de mensagem de erro do grupoError message text for the group |
ds-radio__content | Frame vertical com label, description e helper textVertical frame stacking label, description, and helper text |
ds-radio__label | Texto do label dentro do content frame (label/md)Label text inside content frame (label/md) |
ds-radio__description | Texto descritivo multiline (body/sm, content/default)Multiline description text (body/sm, content/default) |
ds-radio__helper | Texto auxiliar (caption/sm, content/secondary)Helper annotation (caption/sm, content/secondary) |
Propriedades FigmaFigma properties
| PropriedadeProperty | TipoType | PadrãoDefault | DescriçãoDescription |
|---|---|---|---|
Show Label | Boolean | true | Exibe ou oculta o label do controleShows or hides the control label |
Label | Text | "Rótulo" | Texto do label (label/md)Label text (label/md) |
Show Description | Boolean | false | Exibe texto descritivo abaixo do labelShows descriptive text below the label |
Description | Text | "Texto descritivo" | Texto multiline de descrição (body/sm)Multiline description text (body/sm) |
Show Helper Text | Boolean | false | Exibe texto auxiliar abaixo da descriptionShows helper text below the description |
Helper Text | Text | "Texto auxiliar" | Anotação em caption/sm (content/secondary)Caption/sm annotation (content/secondary) |
Interação por tecladoKeyboard interaction
| TeclaKey | AçãoAction |
|---|---|
Tab | Move o foco para dentro do grupo de radio (tab stop único) ou para foraMoves focus into the radio group (single tab stop) or out of it |
Arrow Up / Arrow Left | Seleciona a opção anterior no grupoSelects the previous option in the group |
Arrow Down / Arrow Right | Seleciona a próxima opção no grupoSelects the next option in the group |
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.A radio group behaves as a single tab stop. Arrow keys navigate between options within the group, and selection moves with focus.
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 1.3.1 Info and Relationships (A) | Grupo em <fieldset> + <legend>Group in <fieldset> + <legend> | ✓ |
| 2.4.11 Focus Appearance (AA) | Focus ring visível via :focus-visibleFocus ring visible via :focus-visible | ✓ |
| 2.5.8 Target Size min (AA) | Label estende a área de clique além do radioLabel extends click target beyond the radio itself | ✓ |
| 4.1.2 Name, Role, Value (A) | <input type="radio"> nativo fornece role + estado automaticamenteNative <input type="radio"> provides role + state automatically | ✓ |
| 3.3.1 Error Identification (A) | Erro do grupo comunicado via ds-radio-group--errorGroup error communicated via ds-radio-group--error | ✓ |
Notas de implementaçãoImplementation notes
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.Always wrap radio groups in a <fieldset> with a <legend> to provide group context to screen readers. Uses native <input type="radio"> for built-in keyboard navigation -- arrow keys move between options within a group, Tab enters and exits the group. Focus ring is visible on keyboard focus via :focus-visible.
Label invisível — exige ARIA explícitoInvisible label — requires explicit ARIA
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".When Show Label = false and Show Description = true, link the <input> to the description via aria-labelledby="description-id". If neither is visible, use aria-label directly on the <input>. Helper Text should always be linked via aria-describedby="helper-id".