Pular para o conteúdo
Formulário

RadioGroup

/componentes/radio-group.mdmarkdown cru, para quem lê com agent em vez de olho

Forma de pagamento

Com rótulo

Importar
import { RadioGroup } from '@rivocode/ui'

Quando usar

Agrupa os Radio e cuida da escolha única e da navegação por setas. Passe aria-label ou aponte para um título com aria-labelledby: sem isso o grupo existe para o mouse e não para o leitor de tela.

Quando não usar

Quando as opções não cabem à vista sem tomar meia tela, ou quando vêm do servidor, use Select, ou Combobox se a lista for longa: opção à vista deixa de ser vantagem quando empurra o resto do formulário.

Escolha que muda a vista na hora, como o modo de exibição ou um filtro rápido, é ToggleGroup. Marcar várias é CheckboxGroup. E um sim ou não que vale na hora é Switch; no formulário com Salvar, um Checkbox.

No React Native

Traduz com items na raiz: não há Radio solto para compor, e tudo é controlado.

O label é o aria-label do web com outro nome. Sem nome, o grupo existe para o dedo e não para o leitor de tela. Dentro do FormField, o forValue entrega o rótulo do campo como label, e o grupo sai nomeado sem repetir o texto.

Ele não desenha nada: o texto visível é do Field, como no Select e no Combobox.

API

PropTipoPadrão
defaultValue0.4.0

A opção escolhida de início, no modo não controlado.

unknownsem padrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
form0.4.0

Identifica o formulário dono das opções.

stringsem padrão
inputRef0.4.0

Uma ref para acessar o campo oculto.

Ref<HTMLInputElement>sem padrão
name0.4.0

Identifica o campo quando o formulário é enviado.

stringsem padrão
onValueChange0.4.0

Chamado quando o valor muda.

((value: unknown, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)sem padrão
readOnly0.4.0

Se o usuário fica impedido de escolher outra opção do grupo.

booleanfalse
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, RadioGroupState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
required0.4.0

Se o usuário precisa escolher um valor antes de enviar o formulário.

booleanfalse
value0.4.0

O valor do item de opção escolhido agora, no modo controlado.

unknownsem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

Partes

RadioGroup se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

O círculo, sem rótulo. O texto fica num <label> que envolve os dois, igual ao Checkbox, para o clique no texto também marcar.

Use quando as opções cabem na tela e comparar entre elas importa. Passando de umas cinco, o Select gasta menos espaço.

O rótulo

Passe o texto como filho e o círculo sai dentro de um <label>:

<RadioGroup defaultValue="pix" aria-label="Forma de pagamento">
  <Radio value="pix">Pix</Radio>
  <Radio value="boleto">Boleto</Radio>
</RadioGroup>

Sem filho, sai só o círculo, para quando o rótulo tiver estrutura própria.

Partes

O className veste a raiz: com texto, o <label> inteiro; sem texto, o próprio círculo. classNames veste cada parte pelo nome: circle é o círculo de fora, indicator é a marca de dentro e label é o <label> que embrulha os dois.

<Radio value="pix" classNames={{ circle: 'size-5', indicator: 'size-2.5' }}>
  Pix
</Radio>

O respiro entre o círculo e o texto é o mesmo do Checkbox e do Switch, que aparecem na mesma lista de formulário. E é menor do que o que separa uma opção da seguinte, senão o rótulo ficaria mais perto da opção de baixo do que do próprio círculo.

O círculo marcado

O círculo marcado pinta accent-text, e não accent, com o ponto em surface-raised. É a mesma troca da caixa do Checkbox e do trilho do Switch: com a lima cheia o preenchimento media 1,21:1 sobre a página no tema claro e 1,26:1 sobre o cartão, contra os 3:1 da WCAG 1.4.11. O ponto era grafite e se lia, então o que sumia era a fronteira do círculo - a pessoa via um ponto solto, e não uma opção escolhida.

Com accent-text a fronteira mede 5,55:1 sobre a página e 5,75:1 sobre o cartão, e o ponto mede 5,75:1 dentro do preenchimento. No tema escuro os dois papéis apontam para o mesmo valor, então lá o círculo não mudou de cor.

Desabilitado

Desabilitado se pinta com token, e não com opacidade: o fundo passa a surface-raised e a marca vai para fg-disabled. É a mesma receita do Checkbox, borda inclusive. Ela não muda com o estado. Opacidade rebaixaria tudo de uma vez, e a guarda de contraste do repositório não mede opacidade: o par aprovado no arquivo de tema poderia reprovar na tela sem nada acusar.

Quando não usar

Quando cada opção precisa de descrição, preço ou ícone, e a escolha merece um cartão inteiro como alvo, use RadioCard. Quando as opções passam de umas cinco ou vêm do servidor, Select gasta menos espaço.

Um sim ou não isolado é Checkbox, e não um grupo de dois Radio. Escolha que muda a vista na hora, como o modo de exibição ou um filtro rápido, é ToggleGroup.

PropTipoPadrão
valueobrigatória0.4.0

O valor único que identifica a opção no grupo.

unknownsem padrão
classNames0.5.0

Classe por parte: `circle`, `indicator`, `label`.

Partial<Record<"circle" | "indicator" | "label", string>>sem padrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleansem padrão
inputRef0.4.0

Uma ref para acessar o campo oculto.

Ref<HTMLInputElement>sem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleanfalse
readOnly0.4.0

Se o usuário fica impedido de escolher a opção.

booleansem padrão
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, RadioRootState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
required0.4.0

Se o usuário precisa escolher um valor antes de enviar o formulário.

booleansem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.