RadioButtonGroup

Escolha única em cartões, para opções que precisam de descrição.

O RadioButtonGroup (do HeroUI Pro) oferece uma escolha única em cartões com título e descrição, como a Transportadora ou o Template da Página pública. Para duas ou três opções simples, um rádio comum basta; para muitas, use Select.

import { RadioButtonGroup } from "@rastreio-x/ui";

Padrão

O grupo leva um Label e, opcionalmente, uma Description. Cada RadioButtonGroup.Item tem um value, um indicador e o conteúdo.

TransportadoraAparece na Página pública do Cliente.

PlumaEntregas leves, prazo curto

NimboCobertura nacional

TrilhaCargas maiores

Em grade

layout="grid" coloca os cartões lado a lado. Dê a cada item um aria-label com nome e descrição, porque o nome acessível não sai sozinho do rótulo interno.

Template da Página pública

EssencialSó o que o Cliente precisa

DetalhadoTodos os Marcos e eventos

Rota ao VivoMapa com o trajeto

Com ícones

RadioButtonGroup.ItemIcon põe um ícone à esquerda do conteúdo.

Canal de aviso

E-mailAviso por e-mail

Página públicaLink de acompanhamento

Os doisE-mail com o link

Controlado

Com value e onChange, o estado mostra o efeito da escolha.

Prazo da rota

Flexível25 a 40 dias corridos

FixoSempre 30 dias corridos

Escolha atual: flex

Opção desabilitada

isDisabled no item bloqueia uma opção. Diga no texto por que ela não está disponível.

Canal de aviso

E-mailDisponível

WhatsAppEm breve

Anatomia

RadioButtonGroup
├── RadioButtonGroup.Indicator
├── RadioButtonGroup.Item
├── RadioButtonGroup.ItemContent
└── RadioButtonGroup.ItemIcon

RadioButtonGroup.Item: cada cartão selecionável.
RadioButtonGroup.Indicator: o ponto de seleção (ou um ícone próprio quando marcado).
RadioButtonGroup.ItemContent: título e descrição.
RadioButtonGroup.ItemIcon: ícone opcional à esquerda.

Propriedades

Raiz (RadioButtonGroup):

RadioButtonGroup
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`children`	`ChildrenOrFunction<RadioGroupRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<RadioGroupRenderProps>`	`'react-aria-RadioGroup'`	Classes CSS aplicadas ao elemento.
`defaultValue`	`string \| null`	-	Valor inicial, para uso não controlado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`id`	`string`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isReadOnly`	`boolean`	-	Permite selecionar e copiar o valor, mas não alterá-lo.
`isRequired`	`boolean`	-	Exige um valor antes de enviar o formulário.
`layout`	`'grid' \| 'flex'`	`"flex"`	Opção de animação de layout do motion (`layout`).
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((value: string) => void)`	-	Chamada quando o valor ou a seleção muda.
`orientation`	`Orientation`	`'vertical'`	Orientação do componente: `horizontal` ou `vertical`.
`render`	`DOMRenderFunction<'div', RadioGroupRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<RadioGroupRenderProps>`	-	Estilos em linha aplicados ao elemento.
`validate`	`((value: string) => ValidationError \| true \| null \| undefined)`	-	Função de validação: devolve a mensagem de erro, ou `true` ou `null` quando o valor é válido.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Como validar: `native` usa a validação do navegador; `aria` só marca o estado e anuncia o erro.
`value`	`string \| null`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'primary' \| 'secondary'`	-	Variante visual do componente.

Indicador (RadioButtonGroup.Indicator):

RadioButtonGroup.Indicator
Prop	Tipo	Padrão	Descrição
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Animações

CSS
indicativo

O cartão selecionado troca fundo e indicador em transição CSS curta. Com prefers-reduced-motion, a folha global da fachada reduz a transição a 0,01 ms.

Acessibilidade

É um RadioGroup do React Aria: o grupo tem papel radiogroup e cada cartão, radio.
Tab entra e sai do grupo; as setas movem a escolha; Espaço seleciona.
O Label do grupo nomeia o conjunto; dê aria-label a cada item quando o rótulo interno não bastar.
O selecionado não depende só da cor: o indicador também marca.

Boas práticas

Faça

Título curto e uma descrição que diferencia as opções entre si.

Evite

Opções com a mesma descrição, ou cartões para escolher entre dezenas de itens.

Marque uma opção por padrão quando houver uma escolha segura.
Use cartões para 2 a 5 opções; acima disso, Select.
Em grade, mantenha cartões com a mesma altura de conteúdo.
Escolhas múltiplas pedem Checkbox, não este componente.

Relacionados

Select para listas maiores de opções.
Checkbox para escolhas múltiplas.
Switch para ligar e desligar.