Radio

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.

Visão Geral

O componente br-radio é o controle de formulário do GovBR-DS para seleção de uma única opção dentro de um conjunto mutuamente exclusivo. Compatível com as diretrizes WAI-ARIA, ele integra-se nativamente a formulários HTML via formAssociated.

Para que serve

• Escolha exclusiva: Permite que a pessoa usuária escolha exatamente uma alternativa entre as opções apresentadas no mesmo grupo.
• Integração com formulários: Comunica valor, estado de seleção (checked), desativação e validação diretamente com a API nativa de formulários HTML (ElementInternals).
• Navegação acessível: Suporta foco e seleção via teclado (teclas de seta e barra de espaço) quando agrupado.

Quando utilizar

• Utilize quando:
  • Houver um conjunto pequeno de opções (entre 2 e 5 alternativas) mutuamente exclusivas e for importante manter todas as opções imediatamente visíveis.
• Evite e prefira outro componente quando:
  • O número de opções for superior a 5 ou 7 itens: prefira br-select para economizar espaço de tela.
  • A pessoa usuária puder selecionar múltiplas opções simultaneamente: prefira br-checkbox ou br-checkbox-group.
  • Houver uma escolha binária simples de ativação/desativação imediata: prefira br-switch.

Estrutura e Slots

O br-radio é um controle individual:

• default: Slot para o texto do rótulo da opção (alternativa à propriedade label).

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

checked

Atributo	checked
Descrição	Define o estado de seleção do radio. Se definido como verdadeiro, o radio estará marcado. Caso contrário, estará desmarcado.
Tipo	boolean
Valor padrão	false

customId

Atributo	custom-id
Descrição	Identificador único; gerado automaticamente quando omitido.
Tipo	string
Valor padrão	generateUniqueId()

disabled

Atributo	disabled
Descrição	Desativa o radio, tornando-o não interativo.
Tipo	boolean
Valor padrão	false

feedbackState

Atributo	feedback-state
Descrição	Estado de feedback canônico. Quando informado, tem precedência sobre state.
Tipo	"invalid" | "valid"
Valor padrão	---

hasHiddenLabel Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	has-hidden-label
Depreciação	Use labelHidden.
Descrição	Define se o label associado ao radio deve ser oculto. Se definido como verdadeiro, o texto do label será oculto, mas o radio ainda estará visível e funcional.
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	Texto descritivo exibido à direita do radio. Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado.
Tipo	string
Valor padrão	---

labelHidden

Atributo	label-hidden
Descrição	Oculta visualmente o rótulo. Quando informada, tem precedência sobre hasHiddenLabel.
Tipo	boolean
Valor padrão	---

name

Atributo	name
Descrição	Define o nome do radio, que é utilizado para agrupar radios em formulários e identificar o campo. O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. (obrigatório)
Tipo	string
Valor padrão	---

required

Atributo	required
Descrição	Se verdadeiro, o radio é obrigatório e uma opção deve ser selecionada antes que o formulário possa ser enviado.
Tipo	boolean
Valor padrão	false

state

Atributo	state
Descrição	Indica a validade do radio. Se não for especificado, o valor padrão é null, indicando que a validade não foi definida.
Tipo	"invalid" | "valid"
Valor padrão	---

uncheckOnClick

Atributo	uncheck-on-click
Descrição	Permite desmarcar o radio ao clicar novamente sobre ele quando já estiver selecionado. Por padrão, um radio selecionado permanece marcado ao receber um novo clique. Quando usada junto com uncheckOnDoubleClick, esta opção tem precedência.
Tipo	boolean
Valor padrão	false

uncheckOnDoubleClick

Atributo	uncheck-on-double-click
Descrição	Permite desmarcar o radio ao clicar duas vezes sobre ele. Por padrão, um radio selecionado permanece marcado ao receber um segundo clique.
Tipo	boolean
Valor padrão	false

validator Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada ao estado booleano do radio. Retorne uma mensagem para invalidar ou null para aceitar o valor.
Exemplo de uso	const radio = document.querySelector('br-radio'); radio.validator = (checked) => checked ? null : 'Selecione esta opção';
Tipo	(value: boolean) => string | Promise<string>
Valor padrão	---

value

Atributo	value
Descrição	Define o valor associado ao radio quando ele faz parte de um formulário nativo (<form>). Esse valor é enviado com o formulário quando o radio está selecionado. Nota: Esta propriedade não deve ser utilizada para determinar se o radio está selecionado; para verificar o estado de seleção, use a propriedade checked.
Tipo	string
Valor padrão	---

Slots

Nome	Descrição
"default"	Slot para o rótulo do rádio, como alternativa à propriedade label.
"feedback"	Mensagem de validação, normalmente um br-message.

Eventos

Evento	Descrição	Depreciação	Propagação
brRadioValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Emitido ao iniciar e concluir a validação customizada.	---	true
checkedChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Disparado depois que o valor do checked foi alterado.	Use input/change e leia event.target.checked.	true

Métodos

checkValidity

Descrição	Retorna true se o valor do radio for válido, caso contrário false. Se o radio for inválido, dispara um evento 'invalid'.
Assinatura	checkValidity() => Promise<boolean>
Parâmetros	---

getValidationState

Descrição	Retorna um snapshot serializável da Constraint Validation API.
Assinatura	getValidationState() => Promise<FormValidationState>
Parâmetros	---

reportValidity

Descrição	Retorna true se o valor do radio for válido, caso contrário false. Se for inválido, exibe a mensagem de erro padrão do navegador.
Assinatura	reportValidity() => Promise<boolean>
Parâmetros	---

setCustomValidity

Descrição	Define uma mensagem de validação customizada para o radio. Se a mensagem for uma string vazia, o erro customizado é limpo.
Assinatura	setCustomValidity(message: string) => Promise<void>
Parâmetros	message:

setFocus

Descrição	Move o foco para o input radio nativo interno.
Assinatura	setFocus() => Promise<void>
Parâmetros	---

toggleChecked Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Descrição	Inverte o valor da prop checked
Assinatura	toggleChecked() => Promise<void>
Depreciação	Atualize a propriedade checked diretamente.
Parâmetros	---

validate Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Descrição	Executa o validator do radio e retorna se o valor atual é válido.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Contêiner visual do radio.
"feedback"	Contêiner da mensagem de validação.
"radio-input"	Elemento input nativo do radio.
"radio-label"	Rótulo do radio.

Validação

Para o contrato geral e a matriz de componentes, consulte o guia de formulários. Esta seção documenta o contrato específico do br-radio.

Rádios com o mesmo name formam um grupo. required exige uma opção do grupo e o accessor Angular preserva o valor semântico de value, em vez de expor somente booleano.

Use getValidationState() no grupo/controle e setCustomValidity() para regras de domínio. A mensagem é renderizada automaticamente como br-message quando não existe feedback:

<br-radio name="contato" value="email" label="E-mail" required></br-radio>

Para controlar o conteúdo, use o slot canônico feedback. O rádio referencia o conteúdo com aria-describedby e aria-errormessage; não combine um slot preenchido com outra mensagem visual para evitar duplicidade:

<br-radio name="contato" value="email" label="E-mail">
  <br-message slot="feedback" state="danger">Selecione uma forma de contato.</br-message>
</br-radio>

O reset restaura a opção inicial sem eventos artificiais.

Para regras de domínio síncronas ou assíncronas, use validator com property binding. Ele recebe checked, pode ser acionado por await radio.validate() e emite brRadioValidationChange.

Acessibilidade

Agrupe rádios em fieldset com legend ou forneça um nome equivalente. A roving tabindex mantém somente a opção ativa na ordem de Tab; setas, Home e End mudam a opção conforme o padrão APG.

Mantenha name, value, checked e o label visível. Mensagens de erro devem ser associadas ao grupo e anunciadas em texto.

Eventos nativos

Elemento HTML de referência

br-radio representa <input type="radio">. Cada host contém um radio e controles com o mesmo name formam o grupo.

Como ouvir os eventos

const radio = document.querySelector('br-radio');
radio.addEventListener('change', () => console.log(radio.checked, radio.value));

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
change	radio é selecionado	Sim	Sim	Não	Sim	Não ocorre no radio desmarcado pelo grupo.
click e foco	ativação/navegação	conforme o tipo	Sim	conforme o tipo	Sim	Setas e tabulação seguem o grupo. Com uncheck-on-click, um novo clique no radio selecionado o desmarca.
input	radio é selecionado	Sim	Sim	Não	Sim	Ocorre antes de change.

Eventos não aplicáveis ou não suportados

beforeinput, composição e clipboard não se aplicam. Escrita externa e reset são silenciosos.

Eventos customizados

checkedChange é alias depreciado. Prefira input/change.

Quando uncheck-on-click está habilitado, o segundo clique em um radio selecionado cancela a ação nativa, atualiza checked para false e emite input seguido de change. Em br-radio-group, o valor do grupo passa a ser null. Essa opção tem precedência sobre uncheck-on-double-click quando ambas são informadas.

Valor, frameworks e acessibilidade

Leia checked e value no target; o selecionado participa de FormData. Os wrappers usam o mesmo grupo por name. Setas movem a seleção e há um único ponto de tabulação.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre clique, ordem, flags e FormData; _tests/radio.e2e.tsx cobre foco, setas e grupos em Chromium headless.

Atributos nativos

O host FACE usa name, value, checked, required, disabled, form e autofocus. Radios com o mesmo name mantêm a exclusividade do grupo implementada pelo componente.

form e autofocus seguem a plataforma. Validade, labels e form owner pertencem ao ElementInternals.

Dependências

Depende de

• br-message

Gráfico