Checkbox
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)
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 | br-checkbox-${checkboxId++} |
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
| 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
| 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
| Atributo | --- |
|---|---|
| Descrição | Regra síncrona ou assíncrona aplicada ao estado booleano do checkbox. |
| 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 | Emitido ao iniciar e concluir a validação customizada. | --- | true |
checkedChange | 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
| 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 checkbox e retorna se o valor atual é válido. |
|---|---|
| Assinatura | validate() => Promise<boolean> |
| Parâmetros | --- |
Dependências
Usado por
Depende de
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>
checkbox.addEventListener('change', onChange)
</script>
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/platform-contract.e2e.tsx cobre clique real, ordem, flags, target, caminho, delegação e FormData em Chromium headless.
