Checkbox

Description

Checkbox is a single binary control whose state is true, false, or "indeterminate". It sits at the smallest end of the form scale and is meant for one independent boolean: agree to terms, include a row in a bulk action, opt into a feature.

Reach for it inside table rows, bulk-edit toolbars, parent/child selection trees, and one-off form fields where a full labelled row would be too heavy. For a grouped multi-select with a shared label, helper text, and error message, compose it inside CheckboxGroup. The indeterminate state is for parent rows that summarise a partially-selected set of children.

Don't use Checkbox when the change should commit immediately and visibly. Use Switch for on/off settings, Toggle for in-form binary actions like bold/italic, or RadioGroup when only one of several options can be selected.

Installation

pnpm dlx @create-ui/cli add checkbox

Usage

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

<Checkbox />

Examples

Variants

variant picks the semantic intent of the checked fill: primary for the default action, neutral for system rows, danger/success/info for inline status, and inverse for use on dark surfaces.

Sizes

Three sizes line up with the form-control scale. sm is the default and matches the Input row height; use xs in dense tables and toolbars, or md when a larger control is needed.

Shapes

shape="rounded" (default) follows the size's radius scale. pill is a fully-circular dot, and square keeps hard 0px corners for grid-style selection.

States

The checkbox surfaces four runtime states (unchecked, checked, indeterminate, and disabled) through the Radix data-state attribute. indeterminate is rendered with a minus icon and announces as aria-checked="mixed".

Controlled

Drive the checkbox from state by combining checked and onCheckedChange. The handler receives boolean | "indeterminate" so the same controller can cycle through all three states.

Accessibility

Checkbox is built on Radix UI's Checkbox primitive, so role, focus management, and keyboard handling are handled for you.

ARIA notes:

• The root renders with role="checkbox" and sets aria-checked to "true", "false", or "mixed" (for indeterminate).
• disabled sets data-disabled and removes the element from the tab order.
• The indicator icon is decorative and is not announced; expose the checkbox's purpose via aria-label, aria-labelledby, or a <label htmlFor> association.

Styling

Tailwind override: pass className to merge Tailwind classes with the component's CVA classes:

<Checkbox className="size-7 rounded-full" />

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="checkbox" on the root element.
• data-slot="checkbox-indicator" on the inner indicator span.
• data-variant="<variant>", data-size="<size>", data-shape="<shape>" on the root.
• data-state="checked" | "unchecked" | "indeterminate" (managed by Radix) and data-disabled (only when disabled).

Target a specific state in CSS:

[data-slot="checkbox"][data-state="indeterminate"] {
  /* … */
}

Related Components

• CheckboxGroup: pairs a single checkbox with a label, description, and footer; cascades variant/size/shape via context.
• Switch: immediate on/off setting; use when the change should commit without a submit button.
• RadioGroup: single-select alternative when only one of several options can be active.
• Toggle: in-form binary action button (bold / italic / pin), not a form value.

API Reference

Checkbox

A single binary control. Extends React.ComponentProps<typeof Radix.Checkbox.Root>, so any prop the Radix primitive accepts (checked, defaultChecked, onCheckedChange, required, name, value, id, …) is forwarded.

Props

Variants