When to use it

Use Checkbox for independent yes or no choices, bulk actions, and filter sets where users can select more than one option.

If the user must choose exactly one option from a set, reach for a radio-style pattern instead of trying to coordinate several checkboxes.

State guidance

• Use uncontrolled state for simple forms with defaultChecked.
• Use controlled checked plus onCheckedChange when the surrounding UI needs to reflect aggregate state or persist changes immediately.
• Disabled checkboxes should still keep nearby explanatory copy so people understand why the option is unavailable.

Composition notes

Pair Checkbox with Label so the whole row feels clickable and the accessible name stays explicit. In denser filter lists, keep vertical rhythm on the parent stack instead of adding spacing logic to the checkbox itself.

For bulk actions, place the parent checkbox near the collection title or toolbar action it controls. That makes the indeterminate state easier to interpret at a glance.

When branded styling needs to tune the internal checkmark, prefer the explicit indicatorClassName and iconClassName hooks over descendant selectors. That keeps the control customizable without depending on the primitive's internal SVG structure.