Radio Group
Visão Geral
O br-radio-group agrupa opções de múltipla escolha onde apenas uma pode ser selecionada.
Adicione os elementos br-radio no slot padrão. Defina o rótulo do grupo em label e o valor selecionado em value.
<br-radio-group label="Turno de atendimento" name="turno">
<br-radio value="manha" label="Manhã"></br-radio>
<br-radio value="tarde" label="Tarde"></br-radio>
<br-radio value="noite" label="Noite"></br-radio>
</br-radio-group>
Em formulários HTML, o grupo integra-se via ElementInternals, controlando validação nativa com required.
Quando usar
- Entre 2 e 5 opções mutuamente exclusivas que devem permanecer visíveis.
Quando evitar
- Mais de 6 opções: use
br-selectpara economizar espaço de tela. - Seleção de múltiplas opções ao mesmo tempo: use
br-checkbox-group. - Liga/desliga imediato: use
br-switch.
Consulte as diretrizes de design do GovBR.
Propriedades
ariaLabel
| Atributo | aria-label |
|---|---|
| Descrição | Nome acessível usado quando não há uma legenda visível. |
| Tipo | string |
| Valor padrão | null |
customId
| Atributo | custom-id |
|---|---|
| Descrição | Identificador usado nas relações acessíveis internas. |
| Tipo | string |
| Valor padrão | generateUniqueId() |
defaultValue
| Atributo | default-value |
|---|---|
| Descrição | Valor restaurado por form.reset() e usado como seleção inicial. |
| Tipo | string |
| Valor padrão | --- |
disabled
| Atributo | disabled |
|---|---|
| Descrição | Desabilita o grupo e seus radios. |
| Tipo | boolean |
| Valor padrão | false |
feedbackState
| Atributo | feedback-state |
|---|---|
| Descrição | Estado visual opcional do feedback. Valores inválidos não aplicam estado. A validade real vem de ElementInternals. |
| Tipo | "invalid" | "valid" |
| Valor padrão | --- |
label
| Atributo | label |
|---|---|
| Descrição | Texto visível usado como legenda do grupo. |
| Tipo | string |
| Valor padrão | --- |
name
| Atributo | name |
|---|---|
| Descrição | Nome do campo enviado pelo formulário. (obrigatório) |
| Tipo | string |
| Valor padrão | --- |
orientation
| Atributo | orientation |
|---|---|
| Descrição | Orientação visual das opções. Valores inválidos usam vertical. |
| Tipo | "horizontal" | "vertical" |
| Valor padrão | 'vertical' |
required
| Atributo | required |
|---|---|
| Descrição | Exige uma opção habilitada selecionada. |
| Tipo | boolean |
| Valor padrão | false |
validator
| Atributo | --- |
|---|---|
| Descrição | Regra síncrona ou assíncrona aplicada ao valor do grupo. Recebe a string selecionada ou null quando nenhuma opção está marcada. |
| Exemplo de uso | |
| Tipo | (value: string) => string | Promise<string> |
| Valor padrão | --- |
value
| Atributo | value |
|---|---|
| Descrição | Valor atualmente selecionado; null representa nenhuma seleção. |
| Tipo | string |
| Valor padrão | null |
Slots
| Nome | Descrição |
|---|---|
"default" | Radios pertencentes ao grupo. |
"description" | Texto auxiliar do grupo. |
"feedback" | Mensagem de validação do grupo. |
"label" | Legenda do grupo, como alternativa à propriedade label. |
"validation-loading" | Indicador exibido durante validação assíncrona. |
Eventos
| Evento | Descrição | Depreciação | Propagação |
|---|---|---|---|
brRadioGroupValidationChange | Emitido ao iniciar e concluir uma validação customizada. | --- | true |
Métodos
checkValidity
| Descrição | Verifica a validade do grupo. |
|---|---|
| Assinatura | checkValidity() => Promise<boolean> |
| Parâmetros | --- |
getValidationState
| Descrição | Retorna o snapshot de validade do grupo. |
|---|---|
| Assinatura | getValidationState() => Promise<FormValidationState> |
| Parâmetros | --- |
reportValidity
| Descrição | Verifica a validade e apresenta a mensagem do grupo. |
|---|---|
| Assinatura | reportValidity() => Promise<boolean> |
| Parâmetros | --- |
setCustomValidity
| Descrição | Define a mensagem de validade customizada do grupo. |
|---|---|
| Assinatura | setCustomValidity(message: string) => Promise<void> |
| Parâmetros | message: |
setFocus
| Descrição | Move o foco para o radio marcado ou para o primeiro radio habilitado. |
|---|---|
| Assinatura | setFocus() => Promise<void> |
| Parâmetros | --- |
validate
| Descrição | Executa o validator do grupo. |
|---|---|
| Assinatura | validate() => Promise<boolean> |
| Parâmetros | --- |
CSS Shadow Parts
| Nome | Descrição |
|---|---|
"description" | Área de texto auxiliar. |
"feedback" | Área de mensagem de validação. |
"group" | Fieldset semântico do grupo. |
"legend" | Legenda e nome acessível do grupo. |
"options" | Contêiner das opções. |
"validation-loading" | Área do indicador de validação assíncrona. |
Validação
br-radio-group é o único campo associado ao formulário quando organiza radios. required, setCustomValidity(), checkValidity(), reportValidity() e getValidationState() operam sobre o valor único do grupo; os radios filhos deixam de contribuir individualmente para FormData e para a validade do formulário.
<br-radio-group name="contato" label="Forma de contato" required>
<br-radio name="contato" value="email" label="E-mail"></br-radio>
<br-radio name="contato" value="telefone" label="Telefone"></br-radio>
</br-radio-group>
Sem o slot feedback, a mensagem de required, do validator ou de setCustomValidity() é renderizada automaticamente. Use o slot para controlar a apresentação. Regras síncronas ou assíncronas podem ser atribuídas pela propriedade validator; elas recebem string | null, são executadas em alterações do usuário ou por validate() e emitem brRadioGroupValidationChange.
O estado inicial vem de defaultValue, depois de value ou do último filho inicialmente marcado. form.reset() restaura esse valor sem emitir input ou change. Alterações programáticas também são silenciosas.
Angular e Vue tratam o grupo como um controle de valor único. Em Angular, a diretiva de validade traduz a Constraint Validation API para webComponentValidity; os accessors finais são atualizados pela geração normal dos wrappers.
O grupo normaliza o name dos radios em runtime. Os exemplos também o declaram nos filhos para preservar a tipagem pública obrigatória e retrocompatível de br-radio nos wrappers.
Acessibilidade
O componente usa fieldset e legend, portanto não precisa adicionar role="radiogroup". Informe label, preencha o slot label ou, quando uma legenda visível não for apropriada, use aria-label. Não deixe o grupo sem nome acessível.
Somente o radio marcado participa da ordem de Tab. Sem seleção, o primeiro radio habilitado recebe Tab. Setas movem foco e seleção com retorno circular; Home seleciona o primeiro e End o último. Radios desabilitados são ignorados. O grupo anuncia o valor por meio do estado checked do input nativo de cada br-radio.
O slot description é ligado por aria-describedby; erros são ligados por aria-errormessage e aria-invalid. Mensagens devem continuar visíveis em texto, sem depender apenas de cor ou ícone. Ao falhar em reportValidity(), o foco é enviado para a opção marcada ou para a primeira habilitada.
Apenas filhos br-radio diretos são gerenciados. Essa restrição mantém ordem visual, ordem de teclado e reconciliação dinâmica iguais. Radios adicionados ou removidos são reavaliados automaticamente.
Eventos nativos
Eventos do valor
O grupo intercepta os eventos dos radios e reemite um único input seguido de change no host. Ambos usam bubbles: true e composed: true; leia o valor atual em event.target.value. A opção individual continua expondo checked, mas seu evento não atravessa o grupo como um segundo evento observável.
Setas, Home e End que alteram a seleção produzem a mesma sequência. Escritas em value ou checked, restauração de estado, inclusão/remoção de filhos e form.reset() são programáticos e não emitem esses eventos.
brRadioGroupValidationChange é um evento customizado separado, emitido no início e no fim de uma validação por validator, com { validating, valid, message }.
Atributos nativos
O host é um Form-Associated Custom Element. name, value, required, disabled e a associação nativa por form pertencem ao grupo. Quando habilitado e selecionado, new FormData(form) contém no máximo uma entrada com o name e o value do grupo.
O grupo normaliza o name dos filhos enquanto eles estiverem gerenciados e restaura o valor anterior quando forem removidos. disabled no grupo impede interação, validação e envio; disabled em uma opção apenas a exclui da seleção e da navegação.
default-value define o valor de reset. orientation="horizontal|vertical" muda a disposição visual; não altera a semântica de escolha única.
