RadioGroup
Forma de pagamento
Com rótulo
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
| Prop | Tipo | Padrão |
|---|---|---|
defaultValue0.4.0A opção escolhida de início, no modo não controlado. | unknown | sem padrão |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
form0.4.0Identifica o formulário dono das opções. | string | sem padrão |
inputRef0.4.0Uma ref para acessar o campo oculto. | Ref<HTMLInputElement> | sem padrão |
name0.4.0Identifica o campo quando o formulário é enviado. | string | sem padrão |
onValueChange0.4.0Chamado 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.0Se o usuário fica impedido de escolher outra opção do grupo. | boolean | false |
render0.4.0Troca 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.0Se o usuário precisa escolher um valor antes de enviar o formulário. | boolean | false |
value0.4.0O valor do item de opção escolhido agora, no modo controlado. | unknown | sem 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.
Radio
/radio.mdO 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.
| Prop | Tipo | Padrão |
|---|---|---|
valueobrigatória0.4.0O valor único que identifica a opção no grupo. | unknown | sem padrão |
classNames0.5.0Classe por parte: `circle`, `indicator`, `label`. | Partial<Record<"circle" | "indicator" | "label", string>> | sem padrão |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | sem padrão |
inputRef0.4.0Uma ref para acessar o campo oculto. | Ref<HTMLInputElement> | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
readOnly0.4.0Se o usuário fica impedido de escolher a opção. | boolean | sem padrão |
render0.4.0Troca 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.0Se o usuário precisa escolher um valor antes de enviar o formulário. | boolean | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.