Form
Checkbox Group
Multi-select group of checkboxes sharing a value array. Supports disabled items.
Install
pnpm add @codefast/ui
Import path
@codefast/ui/checkbox-group
Examples
Controlled multi-select
Several options share one value array; a disabled item is skipped.
Granted: read, write
Horizontal layout
Lay items out in a wrapping row.
Working days: Mon, Wed, Fri
With descriptions
Pair each option with a secondary hint.
When someone replies to your thread.
When you’re @-mentioned anywhere.
A Monday summary of activity.
Anatomy
How the parts compose. Copy this skeleton and fill in the slots.
import { CheckboxGroup, CheckboxGroupItem } from "@codefast/ui/checkbox-group";
<CheckboxGroup value={list} onValueChange={setList}>
<CheckboxGroupItem value="read" id="read" />
<Label htmlFor="read">Read</Label>
</CheckboxGroup>
API reference
Props for each part of the component. All native element props are also forwarded.
CheckboxGroup
A multi-selection group sharing one value array.
| Prop | Type | Default | Description |
|---|---|---|---|
| value / onValueChange | string[] / (value: string[]) => void | — | Controlled list of checked values. |
| defaultValue | string[] | — | Initial checked values when uncontrolled. |
| disabled | boolean | false | Disables the whole group. |
CheckboxGroupItem
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | Added to the array when checked (required). |
| disabled | boolean | false | Makes a single item non-selectable. |
Accessibility
Built to be keyboard-navigable and screen-reader friendly out of the box.
| Key | Function |
|---|---|
| Tab | Moves between checkboxes. |
| Space | Toggles the focused item. |
- Each item is a checkbox with its own aria-checked.
- Pair every item with a Label via matching id / htmlFor.
- Use this over loose checkboxes when they share one value.
Guidelines
Conventions that keep usage consistent across an app.
Do
- Use for choosing several options from a set (permissions, filters).
- Keep a disabled item visible to signal an unavailable option.
Don’t
- Don’t use for one-of-many — use Radio Group.
- Don’t leave items unlabelled.