Checkbox

A control that allows the user to toggle between checked and unchecked states. Built on the @base-ui/react Checkbox primitive with a check icon indicator, expanded click target, and focus-visible ring.

Anatomy

A single <Checkbox> renders a 4x4 sized control with data-slot="checkbox". It contains a CheckboxPrimitive.Indicator that shows a check icon when checked. An after pseudo-element expands the click target beyond the visual boundary.

data-slot="checkbox"aria-checkedexpanded click target

Examples

States

Unchecked

Checked

Focused

Disabled

Design Guidelines

Do

  • Always pair with a label. Use Label with htmlFor for click-to-toggle and accessibility.
  • Use for independent boolean choices. Each checkbox should be independently toggleable.
  • Group related checkboxes visually. Stack related options vertically with consistent spacing.

Don't

  • Don't use for mutually exclusive options. Use RadioGroup when only one option can be selected.
  • Don't use without a label. A standalone checkbox without text is not accessible.
  • Don't use for on/off settings. Switch is a better pattern for binary settings with immediate effect.

Developer Reference

Accessibility

  • Built on Base UI Checkbox primitive — manages aria-checked automatically.
  • Focus ring uses focus-visible for keyboard-only display.
  • aria-invalid triggers destructive ring for validation.
  • After pseudo-element creates expanded click target (44px minimum touch area).
  • Indicator shows/hides check icon based on data-checked state.

Usage

import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"

// Basic with label
<div className="flex items-center gap-2">
  <Checkbox id="terms" />
  <Label htmlFor="terms">Accept terms and conditions</Label>
</div>

// Pre-checked
<Checkbox id="newsletter" defaultChecked />

// Disabled
<Checkbox id="disabled" disabled />

// Controlled
const [checked, setChecked] = useState(false)
<Checkbox checked={checked} onCheckedChange={setChecked} />