Inputs/Checkbox

Checkbox

A control that allows the user to toggle between checked and not checked.

Themed

When to Use

Use Checkbox when you need to:

  • Allow users to select multiple options from a list
  • Capture a binary yes/no or agree/disagree choice
  • Enable opt-in features like newsletter subscriptions
  • Accept terms and conditions before form submission
  • Filter or configure settings with independent toggles

When Not to Use

Default

Basic checkbox with a label. Always pair checkboxes with labels for accessibility.

With Text

Checkboxes can include additional descriptive text below the label.

By clicking this checkbox, you agree to the terms and conditions.

Disabled

Disabled checkboxes prevent user interaction and display a muted appearance.

Card Style

A styled card variant with custom colors that responds to the checkbox state using CSS :has() selector.

Checkbox Group

Multiple checkboxes grouped together for selecting multiple options.

Form Integration

Controlled checkbox with state management for form validation.

You must accept the terms to continue.

Checkbox state: unchecked

UX & Design Guidelines

Visual Hierarchy

Keep checkbox labels concise and scannable. Use sentence case for labels. Position checkboxes vertically for lists of 3+ items to improve readability. The checkbox itself should always be left-aligned with labels to the right.

Spacing & Layout

Use gap-3 between checkbox and label for comfortable spacing. For checkbox groups, use space-y-2 between items. When adding description text, align it with the label, not the checkbox.

Responsive Behavior

The 16×16px checkbox size (size-4) works well across devices. Ensure the clickable area includes both checkbox and label for easier touch interaction. Use the card style variant on mobile for larger touch targets.

Color & Contrast

The checked state uses bg-primary with a white check icon for maximum visibility. Error states use border-destructive. Disabled checkboxes reduce opacity to 50% while maintaining the visual structure.

Accessibility

Keyboard Navigation

  • Tab — Move focus to/from the checkbox
  • Space — Toggle the checkbox state
  • Focus moves through checkbox groups in DOM order

Screen Reader Support

  • Always associate checkboxes with labels using htmlFor and id
  • Use aria-describedby to link descriptive text
  • Checkbox announces: label, role (checkbox), and state (checked/unchecked)
  • Use <fieldset> and <legend> for grouped checkboxes

Focus Management

Visible focus ring with 3px width using focus-visible:ring-[3px]. Focus indicator uses ring-ring/50 for a subtle but visible ring. Built on Radix UI Checkbox primitive for full ARIA compliance.

Form Integration

Use required prop for mandatory fields. Set aria-invalid="true" for error states. The name and value props enable native form submission.

ARIA Attributes

{/* Basic accessible checkbox */}
<div className="flex items-center gap-3">
  <Checkbox id="terms" aria-required="true" />
  <Label htmlFor="terms">
    Accept terms <span className="text-destructive">*</span>
  </Label>
</div>

{/* With description */}
<div className="flex items-start gap-3">
  <Checkbox
    id="newsletter"
    aria-describedby="newsletter-description"
  />
  <div>
    <Label htmlFor="newsletter">Newsletter</Label>
    <p id="newsletter-description" className="text-sm text-muted-foreground">
      Get weekly updates about new features.
    </p>
  </div>
</div>

{/* Error state */}
<div className="flex items-center gap-3">
  <Checkbox
    id="error-checkbox"
    aria-invalid="true"
    aria-describedby="error-message"
  />
  <div>
    <Label htmlFor="error-checkbox">Required field</Label>
    <p id="error-message" className="text-sm text-destructive">
      This field is required.
    </p>
  </div>
</div>

Related Components

Radio Group

Use when only one option can be selected from a list.

Switch

Use for settings that take effect immediately.

Toggle

Use for toolbar actions or view preferences.

Label

Always pair with checkboxes for accessibility.

API Reference

The Checkbox component accepts the following props in addition to standard input attributes.

PropTypeDefaultDescription
checkedboolean | "indeterminate"—The controlled checked state of the checkbox.
defaultCheckedbooleanfalseThe default checked state when initially rendered (uncontrolled).
onCheckedChange(checked: boolean | "indeterminate") => void—Event handler called when the checked state changes.
disabledbooleanfalseWhen true, prevents user interaction and applies disabled styles.
requiredbooleanfalseWhen true, indicates the checkbox must be checked for form submission.
namestring—The name of the checkbox for form submission.
valuestring"on"The value given as data when submitted with a name.
idstring—The unique identifier, used to associate with a label.
classNamestring—Additional CSS classes to apply to the checkbox.