Componente estável e recomendada para novos projetos.Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.
O componente br-radio-group é o contêiner semântico e orquestrador de opções br-radio no GovBR-DS, responsável por garantir a exclusividade mútua de seleção, a navegação contínua por teclado e a validação integrada do grupo.
Coordenação de seleção mútua: Garante que apenas um botão de rádio permaneça selecionado por vez entre todos os rádios filhos.
Navegação acessível por teclado WAI-ARIA: Implementa o padrão de navegação com setas direcionais (cima/baixo/esquerda/direita) com foco cíclico dentro do grupo.
Agrupamento semântico: Estrutura o grupo com a semântica de radiogroup, fornecendo rótulo acessível para tecnologias assistivas.
Associação com formulários: Atua como controle integrado (formAssociated), emitindo o valor consolidado selecionado para o formulário pai.
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-groupname="contato"label="Forma de contato"required>
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.
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.
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 }.
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.
