Checkbox

Controle de seleção booleana ou indeterminada com suporte a formulários nativos via ElementInternals.

O mk-checkbox é o controle de seleção booleana do Makuco UI. Representa uma escolha binária (marcado / não marcado) ou, no caso do estado intermediário, uma seleção parcial dentro de um grupo — sendo o componente certo para listas de opções onde múltiplas respostas são válidas ao mesmo tempo, para termos de aceite e para controles de seleção em massa em tabelas. Suporta os estados checked, indeterminate e disabled, integração nativa com formulários e opções de tooltip de ajuda e link externo ao rótulo.

Integração com Angular Forms

Para usar com ngModel ou FormControl, importe MkCheckboxModule em vez de MkCheckboxComponent. Veja Formulários com Angular.

Quando usar

O checkbox é adequado para situações em que o usuário precisa fazer escolhas independentes dentro de um conjunto.

Use quando:

O usuário pode escolher múltiplas opções de uma lista.
A escolha for binária e independente — por exemplo: "Aceito os termos de uso".
Uma seleção "selecionar todos" precisar representar estado parcial (indeterminado).

Prefira uma alternativa quando:

Apenas uma opção puder ser selecionada por vez — use mk-radio.
A escolha for uma ativação/desativação imediata — use mk-switch.

Anatomia

#	Parte	Obrigatório?	Função
1	Controle visual	Sim	Caixa que exibe o estado: vazia, marcada (checkmark) ou indeterminada (traço).
2	Rótulo	Sim	Texto que descreve a opção. Clicar no rótulo também alterna o estado.

Estados

Estado	Quando aparece	O que muda visualmente
Padrão	Estado inicial	Controle com aparência neutra
Hover	Cursor sobre o componente	Destaque suave no controle
Ativo	Clique ou toque em andamento	Feedback de pressão no controle
Desabilitado	Opção indisponível	Opacidade reduzida, sem interação
Erro	Validação exige seleção	Borda ou indicador em vermelho

Padrão

import { MkCheckbox } from '@db1/makuco-ui-react';

<MkCheckbox label="Aceitar termos de uso" />
<MkCheckbox label="Aceitar termos de uso" checked />

<mk-checkbox label="Aceitar termos de uso"></mk-checkbox>
<mk-checkbox label="Aceitar termos de uso" checked></mk-checkbox>

Indeterminado

O estado indeterminate representa uma seleção parcial — comum em checkboxes "selecionar todos". Substitui o ícone de check por um traço e define aria-checked="mixed". Utilize este estado quando alguns, mas não todos os itens de um subgrupo estiverem selecionados, comunicando ao usuário que a seleção é parcial antes de ele interagir.

<MkCheckbox label="Selecionar todos" indeterminate />

<mk-checkbox label="Selecionar todos" indeterminate></mk-checkbox>

Estado de erro

Use error para sinalizar que uma seleção obrigatória não foi feita — por exemplo, quando o usuário tenta avançar sem aceitar os termos de uso. O estado de erro é ignorado quando disabled está ativo.

<MkCheckbox label="Campo obrigatório" error />

<mk-checkbox label="Campo obrigatório" error></mk-checkbox>

Desabilitado

<MkCheckbox label="Opção indisponível" disabled />
<MkCheckbox label="Opção indisponível" disabled checked />

<mk-checkbox label="Opção indisponível" [disabled]="true"></mk-checkbox>
<mk-checkbox label="Opção indisponível" [disabled]="true" checked></mk-checkbox>

Texto de ajuda

Use supportText para exibir um tooltip ao passar o cursor sobre o ícone de interrogação.

<MkCheckbox
  label="Receber notificações"
  supportText="Você receberá e-mails sobre atualizações do sistema"

/>

<mk-checkbox
  label="Receber notificações"
  helper-text="Você receberá e-mails sobre atualizações do sistema"
></mk-checkbox>

Formulários

O mk-checkbox é form-associated: envia value quando checked, e null quando desmarcado.

<form onSubmit={handleSubmit}>
  <MkCheckbox label="Aceitar termos" name="termos" required />
  <MkButton type="submit">Enviar</MkButton>
</form>

<form (ngSubmit)="handleSubmit()">
  <mk-checkbox label="Aceitar termos" name="termos" required></mk-checkbox>
  <mk-button type="submit">Enviar</mk-button>
</form>

Comportamento

O mk-checkbox alterna entre os estados marcado e desmarcado a cada interação do usuário — seja por clique no controle visual ou no rótulo. Quando o prop indeterminate está ativo, ele tem precedência visual sobre checked: o ícone de traço é exibido independentemente do valor de checked. Após o primeiro clique em um checkbox indeterminado, ele passa para o estado marcado ou desmarcado conforme a lógica implementada pelo consumidor.

O componente integra-se ao ciclo de vida de formulários nativos via ElementInternals: quando checked está ativo, o valor definido em value (padrão "on") é enviado com o formulário; quando desmarcado, nenhum valor é submetido. A propriedade required aciona a validação nativa do navegador, impedindo o envio até que o checkbox esteja marcado.

Composição

O mk-checkbox é um componente atômico e não possui subcomponentes. Para agrupar múltiplos checkboxes relacionados, envolva-os em um elemento semântico como <fieldset> com <legend> descrevendo o conjunto — isso garante que leitores de tela anunciem o contexto do grupo ao navegar entre as opções.

Props

Prop	Tipo	Padrão	Descrição
`label`	`string`	`""`	Texto exibido ao lado do checkbox.
`checked`	`boolean`	`false`	Define se o checkbox está marcado.
`indeterminate`	`boolean`	`false`	Estado misto — exibe traço e define `aria-checked="mixed"`. Tem precedência visual sobre `checked`.
`error`	`boolean`	`false`	Ativa o estado de erro com borda e rótulo em vermelho. Ignorado quando `disabled`.
`disabled`	`boolean`	`false`	Desabilita o checkbox, impedindo qualquer interação.
`required`	`boolean`	`false`	Marca como obrigatório para validação de formulário.
`name`	`string`	—	Atributo `name` para envio em formulários.
`value`	`string`	`"on"`	Valor enviado com o formulário quando `checked`.
`supportText`	`string`	—	Conteúdo do tooltip exibido ao passar o cursor sobre o ícone de ajuda.
`link`	`string`	—	URL para o ícone de link externo renderizado após o rótulo.

Eventos

Evento	Payload	Descrição
`mkChange`	`{ checked: boolean; indeterminate: boolean }`	Emitido quando o usuário alterna o checkbox. Suprimido quando `disabled`.

Acessibilidade

Usa <input type="checkbox"> nativo internamente — foco e navegação por teclado (Space para alternar) estão inclusos.
aria-checked="mixed" é definido automaticamente no estado indeterminate.
aria-invalid="true" é aplicado no estado error.
aria-required="true" é aplicado quando required.
A tecla Enter também alterna o estado do checkbox.

Associação do rótulo: o rótulo é programaticamente associado ao controle. Clicar no texto alterna o estado — isso amplia a área de toque e ajuda usuários com dificuldade motora.

Agrupamento: checkboxes relacionados devem ser agrupados em <fieldset> com <legend> descrevendo o conjunto — por exemplo: "Preferências de notificação". Isso garante que leitores de tela anunciem o contexto do grupo ao navegar entre as opções.

Checkbox

On this page