Checkbox Group

Install

pnpm dlx shadcn@latest add @vegastack/checkbox-group

Usage

import { Checkbox } from "@/components/ui/checkbox";
import { CheckboxGroup } from "@/components/ui/checkbox-group";
import { Label } from "@/components/ui/label";

const ALL = ["read", "write", "admin"];

<CheckboxGroup defaultValue={["read"]} allValues={ALL} aria-labelledby="perms">
  <Label>
    <Checkbox parent /> All permissions
  </Label>
  <Label>
    <Checkbox value="read" /> Read
  </Label>
  <Label>
    <Checkbox value="write" /> Write
  </Label>
  <Label>
    <Checkbox value="admin" /> Admin
  </Label>
</CheckboxGroup>;

Built on Base UI Checkbox Group. The group owns the array of ticked values; each child is a plain Checkbox carrying a value. There is no CheckboxGroupItem — a wrapper whose only job is to forward every prop would earn nothing.

Pass allValues and mark one child parent to get the select-all row. Base UI ticks and unticks the whole set from it and drives its mixed (indeterminate) state when only some children are on — the arithmetic that used to be written by hand on every settings page and in every grid header.

Name the group. It renders no label of its own, so give it a wrapping FieldSet + FieldLegend (the strongest form, and the one to prefer in a form) or an aria-labelledby pointing at a heading. An unnamed group announces as a bare list of checkboxes with no idea what they belong to.

Anatomy

<FieldSet>
  <FieldLegend>Permissions</FieldLegend>
  <CheckboxGroup value={value} onValueChange={setValue} allValues={ALL}>
    <Label>
      <Checkbox parent /> All permissions
    </Label>
    <Label>
      <Checkbox value="read" /> Read
    </Label>
  </CheckboxGroup>
</FieldSet>

Examples

Select all

The parent ticks and unticks every value in allValues, and reads mixed while only some children are on.

States

Nothing ticked, some ticked, all ticked — the parent's own state is derived, never assigned.

Uncontrolled

Omit value/onValueChange and pass defaultValue. Without allValues there is no parent, which is the right shape for a plain list of independent options.

Disabled

disabled on the group disables every child, the parent included. The boxes stay hoverable so a Tooltip can explain why they are unavailable.

API Reference

Accessibility

• The group renders a <div> with no implicit name. Wrap it in a FieldSet/FieldLegend, or give it aria-labelledby.
• The parent checkbox exposes aria-checked="mixed" while only some children are ticked, and "true"/"false" at the ends.
• Every checkbox is its own tab stop — a checkbox group is not a roving-tabindex collection, unlike a RadioGroup, because the options are not mutually exclusive.
• disabled on the group removes every child from the tab order.

Do / Don't