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

Design System

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

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

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	---

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

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada ao estado booleano do radio.
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	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

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.

Dependências

Depende de

• br-message

Gráfico

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.
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.

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/platform-contract.e2e.tsx cobre clique, ordem, flags e FormData; _tests/radio.e2e.tsx cobre foco, setas e grupos em Chromium headless.