BaseCheckbox

Marca uma opção que pode ser ligada ou desligada sozinha, ou várias opções de uma lista. É um <input type="checkbox"> nativo com rótulo, ajuda e erro.

Incluir itens já medidos

Só itens com observação do fiscal

Mostra os itens que o fiscal comentou nesta medição

Uso

• Use para escolhas independentes: cada caixa vale por si. Para escolher só uma entre várias, use rádio.
• Para ligar ou desligar uma configuração com efeito imediato, use o switch. A caixa de seleção vale quando a escolha só conta ao salvar o formulário.
• O rótulo diz o que acontece quando a caixa está marcada: "Incluir itens já medidos", não "Itens medidos?".
• Escreva o rótulo em forma afirmativa. Evite "Não enviar aviso", que obriga a pensar em dupla negação.
• hide-label só para selecionar linhas de uma tabela, quando a linha já diz o que é. O rótulo continua para o leitor de tela: "Selecionar item 4.2".
• Não envolva em BaseField; a caixa já tem rótulo, ajuda e erro próprios. Para um grupo com título, use BaseFieldset.
• invalid sozinho, sem invalid-text, só vale para caixas dentro de um <fieldset> cuja mensagem de erro aparece no grupo. Fora de um fieldset, o componente avisa no console em desenvolvimento, porque a borda vermelha seria o único sinal.

Selecionar todos

O estado indeterminate mostra que só parte da lista está marcada. Quem usa o componente calcula esse estado a partir dos itens; o componente não o desliga sozinho.

Selecionar todos os itens

4.2 Alvenaria de vedação

5.1 Chapisco e reboco interno

8.3 Porta de veneziana de alumínio

Estados

Inválido

Confirme que conferiu as medições antes de enviar

Desabilitado

Desabilitado e marcado

Obrigatório *

Parcial e desabilitado

Não há estado somente leitura: o HTML não tem readonly para caixa de seleção. Quando o usuário não pode mudar o valor, mostre o valor como texto ou use disabled e diga o motivo na ajuda.

Tamanhos

Pequeno · texto de 13 px, para filtros e tabelas densas

Médio · texto de 14 px

A caixa tem 16 px nos dois tamanhos; muda só o texto do rótulo. A área de clique tem pelo menos 24 px de altura nos dois tamanhos e termina no fim do texto. Com hide-label, uma área de 24 × 24 px fica centrada na caixa.

Estilo

Propriedade	Token
Fundo	--tj-field-01; desabilitado --tj-field-disabled
Borda	--tj-border-strong-02, hover e foco --tj-border-interactive
Marcado e parcial	--tj-interactive, hover --tj-interactive-hover, pressionado --tj-interactive-active
Desabilitado marcado	--tj-icon-secondary
Erro	--tj-support-error-text (borda, contorno de foco e mensagem), halo --tj-ring-danger
Foco do teclado	contorno sólido de 2 px em --tj-border-interactive, afastado 2 px, mais o halo --tj-ring
Rótulo	--tj-text-primary, --tj-text-md (sm: --tj-text-sm); desabilitado --tj-text-placeholder
Obrigatório	* em --tj-support-error-text
Ajuda	--tj-text-helper, --tj-text-sm
Raio	--tj-radius-sm (4 px)
Movimento	--tj-duration-fast-02, --tj-easing-standard; desligado com prefers-reduced-motion

Código

<BaseCheckbox v-model="aceite" label="Conferi as medições deste mês" :invalid="erro" invalid-text="Confirme que conferiu as medições antes de enviar" required />

<BaseCheckbox :model-value="todos" :indeterminate="alguns" label="Selecionar todos" hide-label @update:model-value="marcarTodos" />

Propriedade	Tipo	Padrão	Descrição
v-model	boolean	false	Marcado ou não
label	string	—	Rótulo (obrigatório)
indeterminate	boolean	false	Parte da lista marcada; quem usa o componente liga e desliga
size	'sm' | 'md'	'md'	Tamanho do texto do rótulo
disabled	boolean	false	Desabilita a caixa
required	boolean	false	Obrigatório no formulário; mostra * ao lado do rótulo
helperText	string	—	Ajuda abaixo do rótulo
invalid / invalidText	boolean / string	—	Erro; a mensagem fica no lugar da ajuda. Sem invalidText, só dentro de um fieldset com a mensagem do grupo
hideLabel	boolean	false	Rótulo só para leitor de tela

Evento: update:modelValue (boolean).

Os demais atributos, como name, value, form, aria-controls e os eventos nativos (@focus, @blur), vão para o <input>. class e style ficam no contêiner.

Ao clicar numa caixa parcial, o componente emite update:modelValue com true e mantém o indeterminate que recebeu. Atualize os itens no evento e recalcule o estado parcial a partir deles, como no exemplo de selecionar todos.

Acessibilidade

• Segue o padrão Checkbox do WAI-ARIA APG. É um <input type="checkbox"> nativo: entra na ordem do Tab e o Espaço marca e desmarca.
• O rótulo é um <label for> ligado à caixa; clicar no texto também marca.
• indeterminate é aplicado como propriedade do elemento, e o navegador anuncia "parcialmente marcado" (aria-checked="mixed"). O componente não grava aria-checked no input, porque o HTML proíbe esse atributo em caixa de seleção nativa.
• Ajuda e erro ficam em aria-describedby. Com erro, a caixa recebe aria-invalid="true". Com invalid-text, a cor nunca é o único sinal: há ícone e texto. Sem ele, o texto do erro precisa estar no fieldset do grupo.
• Obrigatório usa o required nativo e mostra * ao lado do rótulo, como nos demais campos. O * fica escondido do leitor de tela, que já anuncia "obrigatório".
• O foco aparece só na navegação por teclado (:focus-visible), como contorno sólido de 2 px; com erro, o contorno fica vermelho.
• A área de clique tem pelo menos 24 × 24 px (WCAG 2.5.8), inclusive com hide-label.
• Em alto contraste do Windows (forced-colors), a caixa usa cores do sistema: vazia quando desmarcada, preenchida quando marcada, preenchida com um traço quando parcial, e o foco vira contorno em Highlight.
• Com hide-label, o rótulo fica disponível para o leitor de tela. Inclua o nome da linha: "Selecionar item 4.2", não só "Selecionar".
• Para um grupo de caixas com um título comum, use BaseFieldset. Dentro dele, a caixa recebe do grupo o aria-invalid e a mensagem de ajuda, erro ou aviso no aria-describedby.
• Testado com axe em todos os estados, inclusive combinações como parcial e desabilitado. O axe roda sem a regra de contraste, porque o jsdom não desenha a página; o contraste é conferido na documentação renderizada.