Checkbox
Permite selecionar uma ou várias opções de uma lista, de forma independente entre si.
- Selecionar itens de uma lista: escolher um ou vários elementos opcionais dentro de uma lista de dados.
- Ativar filtros em simultâneo: habilitar vários atributos de um filtro ou de uma busca ao mesmo tempo.
- Selecionar linhas de uma tabela: marcar múltiplas linhas para executar ações em massa.
- Confirmar uma aceitação: registrar o consentimento a uma condição pontual, como aceitar termos e condições.
- Escolher uma opção excludente: selecionar uma única opção entre várias mutuamente excludentes. Em vez disso, usar Radio.
- Aplicar uma mudança imediata: ativar ou desativar uma configuração com efeito imediato. Em vez disso, usar Toggle.
- Disparar uma ação: executar algo na hora em vez de registrar uma seleção. Em vez disso, usar Button.
- Container: caixa de seleção que reflete o estado e recebe a interação.
- Icon: marca que aparece dentro do contêiner conforme o estado: um check quando está marcado ou uma linha quando é indeterminate.
- Label: texto que descreve a opção que o controle representa.
Primary: aparência por padrão.
Danger: sinaliza um erro de validação na seleção. Ex.: um checkbox obrigatório que ficou sem marcar ao enviar o formulário.
aiGenerated: aplica uma borda com degradê de IA para indicar que o valor foi sugerido por inteligência artificial. Ex.: uma opção pré-preenchida por uma sugestão automática.
Costuma aparecer em formulários, listas de opções, painéis de configuração e filtros, junto ao label que descreve a opção para deixar claro o que está sendo ativado ou desativado.
Usar checkbox quando as opções não são excludentes e é possível escolher mais de uma.
Não usar checkbox para opções mutuamente excludentes; nesse caso usar Radio.
Redigir o label em positivo, descrevendo o que é ativado ao marcar o checkbox.
Evitar labels em negativo: ao marcá-los, geram uma dupla negação difícil de interpretar.
Reservar o estado indeterminate para um checkbox que resume uma seleção parcial do seu grupo.
Não usar indeterminate em um checkbox solto: só faz sentido quando resume a seleção parcial de um grupo.
- Label associado: acompanhar sempre o controle com um label que descreva a opção, para que leitores de tela anunciem do que se trata.
- Navegação por teclado: o checkbox é alcançável com Tab e é marcado ou desmarcado com a barra de espaço.
- Foco visível: o controle mostra um anel de foco ao navegar com teclado, sem depender do ponteiro.
- Não depender só da cor: a aparência danger é acompanhada de um texto de erro ou ajuda, já que a cor sozinha não comunica o problema.
O label do Checkbox descreve o que é ativado ao selecioná-lo, não o estado técnico nem a ação de marcar. Se ele não funcionar por si só, sem depender do que está em volta, precisa ser reescrito.
- Capitalização: primeira letra sempre maiúscula. O label de grupo também vai em sentence case, sem ponto final.
- Pontuação: sem ponto nem vírgula no final. Exceção: os labels de aceitação de termos ou políticas são frases completas e levam ponto final.
- Enquadramento positivo: descrever o que é ativado, não o que é evitado. "Mostrar preços com IVA incluído", não "Ocultar preços sem IVA".
- Autonomia do label: precisa funcionar por si só, sem depender do texto que o rodeia.
- Ordem: as opções de uma lista devem seguir um critério lógico (alfabético, numérico, temporal ou outro critério claro).
- Forma verbal: com verbo ("Receber notificações") ou sem verbo ("Notificações por e-mail") são válidas as duas; manter a mesma forma dentro do mesmo grupo de opções.
- Aceitação de termos: "Estou de acordo com [termos/política]" ou "Concordo com [termos/política]".
| Caso | O que fazer |
|---|---|
O label precisa de mais explicação | Adicionar help text. Não alongar o label nem usar um tooltip para informação crítica. |
Estado indeterminate (seleção parcial de um grupo) | Não escrever um label específico para esse estado; o estado visual já comunica isso. |
Seleção em massa em uma tabela | Sem label visível. Adicionar um aria-label descritivo, por exemplo "Selecionar todos os produtos". |
Instale o componente via terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { Checkbox } from "@nimbus-ds/components";
const Example: React.FC = () => <Checkbox name="my-checkbox" label="Label" />;
export default Example;Propriedades adicionais são repassadas ao elemento <Checkbox>. Consulte a documentação do elemento input para ver a lista de atributos aceitos.
Checkbox
| Name | Type | Default | Description |
|---|---|---|---|
name* | string | The name of the input element. | |
appearance | 'danger' | 'neutral' | Change the visual style of the checkbox. |
checked | boolean | Modifies true/false value of the native checkbox. | |
disabled | boolean | Modifies the native disabled state of the native checkbox. | |
indeterminate | boolean | 'false' | If true, the component appears indeterminate. This does not set the native input element to indeterminate due to inconsistent behavior across browsers. However, we set a data-indeterminate attribute on the input. |
label | string | Text to be rendered inside the component. | |
aiGenerated | boolean | 'false' | Highlights the checkbox to indicate its value was generated by AI. Applies AI gradient border that persists regardless of checked state. |
Checkbox.Skeleton
| Name | Type | Default | Description |
|---|---|---|---|
width | string | Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own. | |
className | string | ||
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
Ajude-nos a melhorar a documentação
Encontrou um problema ou tem uma sugestão? Conte para a gente.