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 br-checkbox marca ou desmarca uma opção independente. Funciona em formulários como um <input type="checkbox">: é enviado com name e value quando está marcado.

<br-checkbox name="termos" value="aceito" label="Li e aceito os termos" required></br-checkbox>

Use indeterminate para indicar seleção parcial, por exemplo em um "selecionar todos" quando só parte dos itens está marcada.

Quando usar

• Opções em que escolher uma não impede escolher outra.
• Confirmar uma condição, como aceitar termos.

Quando evitar

• Só uma opção pode ser escolhida: use br-radio-group.
• A mudança vale na hora, sem enviar formulário: use br-switch.
• Muitas opções em pouco espaço: use br-select com multiple.

Para várias opções da mesma pergunta, agrupe-as em um br-checkbox-group.

Consulte as diretrizes de design do GovBR.

Exemplos

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

Com required, o checkbox precisa estar marcado para o formulário ser válido. Consulte a validade com checkValidity() e mostre a mensagem com reportValidity().

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

Mensagem própria

Coloque a mensagem no slot feedback. Sem ele, o componente mostra a mensagem de validação em um br-message.

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

Regra personalizada

Atribua uma função a validator. Ela recebe o estado (checked) e retorna uma mensagem para invalidar ou null para aceitar. Chame validate() para executar e aguardar o resultado.

const checkbox = document.querySelector('br-checkbox');
checkbox.validator = (checked) => (checked ? null : 'Confirme para continuar.');
const valido = await checkbox.validate();

Para regras fora do componente, use setCustomValidity('mensagem') e limpe com setCustomValidity('') quando o problema for corrigido.

Veja também o guia de formulários.

Acessibilidade

Use um rótulo visível, com label ou com o conteúdo do checkbox. Espaço marca e desmarca. A seleção parcial é anunciada como "misto".

Mostre erros com texto, não só com cor. A mensagem do slot feedback é associada ao campo automaticamente.

Eventos nativos

Ouça input e change, como em um <input type="checkbox">. Os dois ocorrem uma vez a cada clique ou Espaço, nessa ordem.

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

Mudar checked pelo código, limpar o formulário ou carregar a página não emite input nem change.

indeterminateChange avisa quando a seleção parcial muda. checkedChange ainda funciona, mas está depreciado: use change.

Atributos nativos

Como um checkbox nativo, aceita name, value, checked, indeterminate, required, disabled, form e autofocus. Só é enviado no formulário quando está marcado.

Dependências

Usado por

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

Depende de

• br-message

Gráfico

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

1.x	2.x	O que fazer
dataChild	br-checkbox-group	Agrupe as opções no br-checkbox-group, que já cria o "selecionar tudo".
inline	—	Remova e organize o layout no contêiner.
invalid / valid	state	Use state="invalid" ou state="valid".
label, checked, disabled, required, name, value	mesmos nomes	Mantenha.
update:checked	change	Ouça o evento nativo e leia event.target.checked.

1.x:

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

2.x:

<br-checkbox checked label="Aceito"></br-checkbox>

document.querySelector('br-checkbox').addEventListener('change', (event) => onChange(event.target.checked));