Installation

Barrel

// code example

Granular

// code example

Usage

export default function Example() {
  return <Checkbox label="Accept terms" />;
}

Examples

Default

Checkbox with built-in label. The label automatically displays in a horizontal layout (checkbox before label).

Checked

Indeterminate

Used for "select all" patterns when some but not all items are selected.

Label First Layout

Use controlFirst={false} to place the label before the checkbox.

Disabled

Error

Error variant provides visual styling (red ring). For error messages, use Checkbox.Group.

Checkbox Group

Group multiple checkboxes with a legend, description, and shared error messages. Uses Checkbox.Group and Checkbox.Item.

Checkbox Group with Error

Show validation errors at the group level. Error replaces description when present.

Visually Hidden Legend

Use Checkbox.Legend with className="sr-only" to keep the legend accessible to screen readers while hiding it visually. This is useful when the group is already labeled by a parent Field or heading, and showing the legend would create a redundant label.

Custom Legend Styling

Checkbox.Legend accepts className for full control over legend presentation. Use it instead of the legend string prop when you need custom typography, colors, or layout.

API Reference

Checkbox

Single checkbox component with built-in label and horizontal layout.

Checkbox.Group

Wrapper for multiple checkboxes with legend, description, and error support.

Checkbox.Legend

Composable legend sub-component for Checkbox.Group. Accepts className for full styling control (e.g. className="sr-only" to visually hide). Use instead of the legend string prop when you need custom legend styling.

Checkbox.Item

Individual checkbox within Checkbox.Group.

Accessibility

  ### Label Requirement

  
    Single checkboxes require a `label` prop or `aria-label` for accessibility.
    Missing labels trigger console warnings in development.
  



  ### Keyboard Navigation

  
    <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Space</kbd> toggles
    the checkbox.
    <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Tab</kbd> moves focus
    between checkboxes.
  



  ### Screen Readers

  
    Checkbox.Group uses semantic `&lt;fieldset&gt;` and `&lt;legend&gt;` elements for
    proper grouping announcement.