Checkbox Group React component
A group of checkboxes with a Select all row that shows a dash when only some are picked, checks that draw themselves, list or card layouts, a maximum that disables the rest, a live count and an error state.
When to use the Checkbox Group component
Use Checkbox Group when people can pick any number of options from a short list: notification topics, filters, add-ons, permissions. Select all with its in-between state makes long lists quick to clear or fill.
Use the cards variant when each option needs a description and should feel like a choice, and max when there's a real limit ("pick up to two"). For a single choice use Radio Button or Segmented Control.
Installation
Add the Checkbox Group component to your project with the shadcn CLI. It lands in components/checkbox-group.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add https://reactframe.com/r/checkbox-group.jsonOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<CheckboxGroup /> accepts 18 props, all optional.
| Prop | Type | Default |
|---|---|---|
| options | { value: string; label: string; description?: string; disabled?: boolean }[] | DEFAULT_OPTIONS |
| value | string[] | — |
| defaultValue | string[] | ["product"] |
| onValueChange | (value: string[]) => void | — |
| label The group's legend. | string | "Email preferences" |
| description | string | — |
| selectAll A "Select all" row above the options that shows a dash when only some are picked. | boolean | true |
| selectAllLabel | string | "Select all" |
| variant list: rows with a box on the left. cards: bordered tiles that light up when picked. | "list" | "cards" | "list" |
| orientation | "vertical" | "horizontal" | "vertical" |
| max At most this many can be picked; the rest disable once it's reached. | number | — |
| error Error text to show (e.g. "Pick at least one"). | string | — |
- options{ value: string; label: string; description?: string; disabled?: boolean }[]Default: DEFAULT_OPTIONS
- valuestring[]
- defaultValuestring[]Default: ["product"]
- onValueChange(value: string[]) => void
- label
The group's legend.
stringDefault: "Email preferences" - descriptionstring
- selectAll
A "Select all" row above the options that shows a dash when only some are picked.
booleanDefault: true - selectAllLabelstringDefault: "Select all"
- variant
list: rows with a box on the left. cards: bordered tiles that light up when picked.
"list" | "cards"Default: "list" - orientation"vertical" | "horizontal"Default: "vertical"
- max
At most this many can be picked; the rest disable once it's reached.
number - error
Error text to show (e.g. "Pick at least one").
string
Show all 18 propsShow fewer
| showCount | boolean | true |
| name | string | — |
| disabled | boolean | false |
| size | "sm" | "md" | "lg" | "md" |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- showCountbooleanDefault: true
- namestring
- disabledbooleanDefault: false
- size"sm" | "md" | "lg"Default: "md"
- theme"dark" | "light"Default: "dark"
- classNamestring
FAQ
- Does it work with a plain form submit?
- Yes. Each option is a real checkbox; give the group a name and the checked values are posted like any other checkboxes.
- What does the Select all dash mean?
- Some but not all options are picked (the indeterminate state). Clicking it picks the rest, or clears them all when everything is already picked.
- How does max work?
- Once that many are picked, the remaining options disable and the count shows "2 of 2". Unpicking one frees them again.
