Checkbox

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-checkbox é o controle de formulário oficial do GovBR-DS para seleção binária independente (marcado ou desmarcado) ou intermediária (indeterminada). Compatível com as diretrizes WAI-ARIA para checkboxes, ele integra-se nativamente a formulários HTML via formAssociated.

Para que serve

• Seleção independente múltipla: Permite que a pessoa usuária escolha qualquer quantidade de opções (zero, uma ou várias) de uma lista de alternativas independentes.
• Confirmação e aceite binário: Utilizado para termos de uso, declarações de concordância e confirmações obrigatórias.
• Estado indeterminado: Suporta a propriedade indeterminate, essencial para checkboxes mestres em listas hierárquicas (indicando que parte dos itens filhos está marcada).
• Validação e formulários: Comunica valor, estado de validação e mensagens contextuais de erro (feedback) diretamente com a API nativa de formulários HTML (ElementInternals).

Quando utilizar

• Utilize quando:
  • Houver uma lista de opções onde a seleção de uma alternativa não anula nem depende das demais.
  • O usuário precisar confirmar explicitamente uma condição única (ex.: "Li e concordo com os termos").
  • For necessário criar controle de seleção em lote ("Selecionar todos").
• Evite e prefira outro componente quando:
  • As opções forem mutuamente exclusivas (apenas uma pode ser escolhida): prefira br-radio ou br-radio-group.
  • A ação ativar ou desativar instantaneamente um recurso sem exigir submissão de formulário: prefira br-switch.
  • Houver muitas opções (mais de 7) em espaço reduzido: prefira br-select múltiplo.

Estrutura e Slots

O br-checkbox é um controle autônomo com slots de suporte:

• default: Slot para o texto do rótulo associado ao checkbox (alternativa à propriedade label).
• feedback: Slot para exibição de mensagens de validação e alertas contextuais (como br-message).

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

PadrãoMarcadoIndeterminadoObrigatório inválidoDesabilitado

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 checkbox. Se definido como verdadeiro, o checkbox estará marcado. Caso contrário, estará desmarcado.
Tipo	boolean
Valor padrão	false

customId

Atributo	custom-id
Descrição	Identificador único. Caso não seja fornecido, um ID gerado automaticamente será usado.
Tipo	string
Valor padrão	generateUniqueId('br-checkbox')

disabled

Atributo	disabled
Descrição	Desativa o checkbox, 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 checkbox deve ser oculto. Se definido como verdadeiro, o texto do label será oculto, mas o checkbox ainda estará visível e funcional.
Tipo	boolean
Valor padrão	false

indeterminate

Atributo	indeterminate
Descrição	Define o estado intermediário do checkbox. Quando verdadeiro, exibe uma marcação parcial visual que indica seleção parcial. Útil para representar grupos onde alguns itens estão selecionados, mas não todos. Ao clicar no checkbox neste estado, ele será automaticamente alterado para marcado.
Tipo	boolean
Valor padrão	false

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

Atributo	is-father
Depreciação	Configure seleção coletiva em br-checkbox-group/br-checkgroup.
Descrição	Indica se o checkbox é pai de um grupo de checkboxes.
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	Texto descritivo exibido à direita do checkbox. 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 checkbox, que é utilizado para agrupar checkboxes 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 checkbox é obrigatório e deve ser marcado antes que o formulário possa ser enviado.
Tipo	boolean
Valor padrão	false

state

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

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 checkbox. Retorne uma mensagem para invalidar ou null para aceitar o valor.
Exemplo de uso	const checkbox = document.querySelector('br-checkbox'); checkbox.validator = (checked) => checked ? null : 'Confirme para continuar';
Tipo	(value: boolean) => string | Promise<string>
Valor padrão	---

value

Atributo	value
Descrição	Define o valor associado ao checkbox quando ele faz parte de um formulário nativo (<form>). Esse valor é enviado com o formulário quando o checkbox está selecionado. Nota: Esta propriedade não deve ser utilizada para determinar se o checkbox 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 checkbox, como alternativa à propriedade label.
"feedback"	Mensagem de validação, normalmente um br-message.

Eventos

Evento	Descrição	Depreciação	Propagação
brCheckboxValidationChange 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
indeterminateChange	Disparado depois que o valor do indeterminate foi alterado.	---	true

Métodos

checkValidity

Descrição	Retorna true se o valor do checkbox for válido, caso contrário false. Se o checkbox 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 checkbox 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 checkbox. Se a mensagem for uma string vazia, o erro customizado é limpo.
Assinatura	setCustomValidity(message: string) => Promise<void>
Parâmetros	message:

setIndeterminate

Descrição	Define o estado indeterminado do checkbox.
Assinatura	setIndeterminate(value: boolean) => Promise<void>
Parâmetros	value: Novo valor para o estado indeterminado.

setNumberOfChildren

Descrição	Define o número de checkboxes filhos em um grupo de checkboxes.
Assinatura	setNumberOfChildren(value: number) => Promise<void>
Parâmetros	value: Número de checkboxes filhos.

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 checkbox 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 checkbox.
"feedback"	Contêiner da mensagem de validação.
"input"	Elemento input nativo do checkbox.
"label"	Rótulo do checkbox.

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

Use required para exigir que checked seja verdadeiro. O valor enviado usa name e value; a validade pode ser consultada por checkValidity()/getValidationState() ou apresentada por reportValidity().

Para uma regra de negócio, use setCustomValidity() e limpe a mensagem quando o usuário corrigir a seleção. A mensagem é renderizada automaticamente como br-message quando não existe feedback:

<br-checkbox id="termos" name="termos" required label="Aceito os termos"></br-checkbox>

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

<br-checkbox id="termos" name="termos" label="Aceito os termos">
  <br-message slot="feedback" state="danger">Você deve aceitar os termos.</br-message>
</br-checkbox>

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

Acessibilidade

Use label textual visível. O componente expõe semântica de checkbox, mantém checked e aria-checked sincronizados e delega foco ao controle nativo interno. A tecla Espaço alterna o estado; Enter não deve ser usado como substituto.

Associe instruções e erros com aria-describedby/aria-errormessage e não comunique erro apenas por cor.

Eventos nativos

Elemento HTML de referência

br-checkbox representa <input type="checkbox"> e mantém esse controle dentro do Shadow DOM.

Como ouvir os eventos

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

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
change	estado alterna	Sim	Sim	Não	Sim	Uma ocorrência por clique.
click	ativação por ponteiro/Space	Sim	Sim	Sim	Sim	Preservado pelo navegador.
input	estado alterna	Sim	Sim	Não	Sim	Ocorre antes de change.
eventos de foco	foco entra ou sai	conforme o tipo	Sim	Não	Sim	Delegação usa focusin/focusout.

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

beforeinput, composição e clipboard não se aplicam. Escrita em checked, reset e inicialização não emitem input/change.

Eventos customizados

checkedChange é alias depreciado; indeterminateChange comunica o estado adicional indeterminate.

Valor, frameworks e acessibilidade

Leia event.target.checked e value; somente marcado participa de FormData. HTML, React, Angular e Vue recebem o par nativo. Space alterna o controle e aria-checked="mixed" representa indeterminado.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre clique real, ordem, flags, target, caminho, delegação e FormData em Chromium headless.

Atributos nativos

O host FACE usa name, value, checked, indeterminate, required, disabled, form e autofocus. form e autofocus são atributos da plataforma, não props artificiais.

Validade, labels e form owner são mantidos pelo ElementInternals. O estado serializável para wrappers é obtido por getValidationState().

Dependências

Usado por

• br-checkbox-group
• br-cookiebar
• br-cookiebar-group
• br-select-option

Depende de

• br-message

Gráfico

Migração de <br-checkbox> (1.x → 2.x)

O checkbox mantém o elemento e o modelo de seleção, mas a validação e a comunicação de mudanças seguem a API nativa e as propriedades de estado atuais.

Propriedades e eventos

API 1.x	API 2.x	Ação na migração
checked, disabled, required, name, value	mesmos nomes	Mantenha e revise a passagem de atributos.
dataChild	isFather	Mantenha apenas quando estiver migrando uma relação pai/filhos; prefira br-checkbox-group para agrupamento.
inline	—	Remova; organize o layout no contêiner.
invalid / valid	state	Use o estado semântico atual.
label	label ou slot	Mantenha a propriedade ou use conteúdo customizado.
update:checked	input / change	Escute os eventos nativos do Web Component.

Exemplo

1.x:

<br-checkbox :checked="value" label="Aceito" @update:checked="onChange"></br-checkbox>

2.x:

<br-checkbox checked label="Aceito"></br-checkbox>
<script>
  document.querySelector('br-checkbox').addEventListener('change', onChange);
</script>