Checkbox

Visual Variants

Size Variants

Label Position

Checkbox Properties

Important: The indeterminate state is visual only — it does not affect the underlying checked value. When a user clicks an indeterminate checkbox, you decide what happens (typically it becomes fully checked). This logic is your responsibility.

Design Token Mappings

For a full reference on token architecture, see our Design Tokens Complete Guide.

Checkbox States

Check Animation

A well-crafted check animation adds polish. The checkmark should "draw" in (stroke-dashoffset animation on an SVG path) over 100–150ms. Avoid bouncy or slow animations — the checkbox should feel instant and crisp.

.checkbox-icon path {
  stroke-dasharray: 20;
  stroke-dashoffset: 20;
  transition: stroke-dashoffset 150ms ease-out;
}
.checkbox[aria-checked="true"] .checkbox-icon path {
  stroke-dashoffset: 0;
}

WCAG Requirements

ARIA Attributes

• Native checkbox (<input type="checkbox">): Needs no ARIA — the role and checked state are built in. Just pair it with a <label>.
• Custom checkbox (<div role="checkbox">): Must implement role="checkbox", aria-checked="true|false|mixed", tabindex="0", and handle Space key to toggle.
• Indeterminate: Use aria-checked="mixed" for custom implementations. For native checkboxes, set the .indeterminate DOM property (there's no HTML attribute for it).
• Checkbox group: Wrap in a <fieldset> with a <legend> to group related checkboxes. The legend becomes the group label for screen readers.
• Error state: Associate error text with aria-describedby and use aria-invalid="true".

Keyboard Interaction

Note: Unlike radio buttons, checkboxes in a group do not use arrow keys for navigation. Each checkbox is independently focusable via Tab. This is an important distinction.

Common Mistakes

1. Forgetting to make the label clickable. The label should toggle the checkbox — not just sit next to it. Use <label> wrapping or for attribute.
2. Using aria-checked on a native checkbox. Don't — it's redundant and can cause double announcements.
3. Not handling indeterminate in screen readers. Native <input> with .indeterminate = true announces as "mixed" in most screen readers. Verify this.

For more, see our ARIA Attributes Guide and Keyboard Accessibility Guide.

Do's

• ✅ Always provide a visible label. Even in table rows, ensure column headers serve as the implicit label, and add aria-label for screen readers.
• ✅ Use a fieldset + legend for checkbox groups. This gives screen readers the group context ("Notification preferences: Email, SMS, Push").
• ✅ Make the entire row clickable (label + checkbox), not just the tiny box. This is a massive usability win on touch devices.
• ✅ List options in a logical order — alphabetical, by frequency, or by importance. Don't randomize.
• ✅ Use positive framing. "Enable notifications" not "Disable notification silence." Double negatives confuse everyone.
• ✅ Show selected count when checkboxes control a bulk action: "3 items selected".

Don'ts

• ❌ Don't use a checkbox for a single binary choice that takes effect immediately. That's a Switch.
• ❌ Don't pre-check opt-in checkboxes. Especially for marketing consent — this may violate GDPR and is hostile UX. Default to unchecked.
• ❌ Don't use more than 7 checkboxes in a visible group without structure. Beyond that, add subgroups, search, or a different pattern entirely.
• ❌ Don't align checkboxes horizontally unless you have 2–3 short-label options. Vertical stacking is far more scannable.
• ❌ Don't use round checkboxes. Square = multi-select (checkbox). Round = single-select (radio). This convention is deeply ingrained. Breaking it confuses users.

Content Guidelines

• Labels: Sentence case, positive framing, 1–5 words
• Group legend: Descriptive question or statement ("Which notifications would you like?")
• Required groups: Add "(required)" to the legend or use aria-required on the group
• Error messages: Be specific ("Select at least one notification method" not "Required field")

Cross-System Comparison

Notable Approaches

Radix Checkbox is a <button> with role="checkbox" rather than a native <input type="checkbox">. This is intentional — it gives full styling control (native checkboxes are notoriously hard to style consistently across browsers) while maintaining accessibility. The trade-off: it doesn't participate in native form submission without a hidden <input> companion, which Radix handles internally.

Material 3 adds a ripple effect to checkbox interactions, consistent with their touch feedback philosophy. The ripple radiates from the point of click — a nice detail for touch interfaces. They also support an "error" state where the checkbox border turns red, which is less common but useful for required agreement checkboxes.

Ant Design's Checkbox.Group is remarkably convenient — you pass an options array and get a fully managed group with a value array and onChange callback. This declarative approach reduces boilerplate significantly for common "pick multiple" forms.

Native vs. custom: The eternal debate. Native <input type="checkbox"> is accessible by default and participates in form submission, but is nearly impossible to style consistently. Custom implementations (<button role="checkbox"> or <div role="checkbox">) offer full visual control but require manual accessibility work. Most modern design systems opt for custom with careful ARIA implementation. The native accent-color CSS property (supported in all modern browsers as of 2026) provides a middle ground — it lets you change the checkbox color while keeping native behavior.