Skip to Content
ComponentsAtomsCheckbox

Checkbox

Atom

Checkbox representa uma escolha independente. Use quando a seleção será aplicada, enviada ou combinada com outras decisões.

Diferente de Switch, Checkbox normalmente participa de uma submissão, filtro, seleção em lote ou confirmação explícita. Em contexto operacional, o texto precisa deixar clara a consequência da seleção.

Exemplos copiáveis

React

import * as React from "react"
 
type PulsoCheckboxProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type"> & {
  label: string
  description?: string
}
 
export function PulsoCheckbox({ id, label, description, className, ...props }: PulsoCheckboxProps) {
  const reactId = React.useId()
  const checkboxId = id ?? reactId
  const descriptionId = description ? `${checkboxId}-description` : undefined
 
  return (
    <label className="inline-flex cursor-pointer select-none items-start gap-2.5">
      <input
        id={checkboxId}
        type="checkbox"
        aria-describedby={descriptionId}
        className={[
          "mt-0.5 h-4 w-4 rounded-[var(--radius-xs)] border border-[var(--border-strong)] bg-[var(--card)]",
          "accent-[var(--primary)] transition-colors duration-[var(--motion-duration-fast)] ease-[var(--motion-easing)]",
          "focus-visible:outline focus-visible:outline-[var(--ring-width)] focus-visible:outline-offset-2 focus-visible:outline-[var(--ring)]",
          "disabled:cursor-not-allowed disabled:opacity-60",
          className,
        ].filter(Boolean).join(" ")}
        {...props}
      />
 
      <span className="grid gap-0.5">
        <span className="text-sm font-medium text-[var(--fg-strong)]">{label}</span>
        {description ? (
          <span id={descriptionId} className="text-xs text-[var(--fg-muted)]">
            {description}
          </span>
        ) : null}
      </span>
    </label>
  )
}
<PulsoCheckbox
  label="Incluir fontes arquivadas"
  description="Mostra fontes inativas apenas neste filtro."
/>

Quando usar

  • Seleção múltipla em filtros.
  • Seleção de linhas ou itens em lote.
  • Confirmação explícita antes de aplicar uma ação.
  • Preferências que serão salvas em formulário.

Quando não usar

  • Para ligar/desligar comportamento imediato; use Switch.
  • Para escolher exatamente uma opção; use Radio Group ou Select.
  • Para ação primária; use Button.
  • Para esconder uma consequência operacional importante.

Acessibilidade

  • Associe label e controle no mesmo label ou com htmlFor.
  • Use aria-describedby para descrição ou consequência.
  • Em tabelas, exponha seleção parcial como aria-checked="mixed" quando aplicável.
  • Não dependa apenas de cor para indicar selecionado.

Regras

  1. Checkbox é escolha independente ou múltipla.
  2. Label deve dizer o que será selecionado.
  3. Descrição explica consequência, não repete o label.
  4. Seleção em lote precisa deixar claro o escopo afetado.
  5. Para risco operacional, não use checkbox sem texto de consequência.
Last updated on
ChartChip