Checkbox Group
A group of checkboxes that allows multiple selections with support for validation and accessibility.
Installation
Installation with shadcn/ui
CLI
Manual
Install the following dependencies:
Copy and paste the following code into your project.
Layout
Import the parts, and compose them together.
Animated Checkbox
Update tailwind.config.ts
to include the following animation:
Copy and paste the CheckboxGroup.Indicator
block from the following example into your project.
Examples
Horizontal Orientation
With Validation
Validate the group with onValidate
or required
prop. Can be used for native form validation.
Multi Selection
Hold down the Shift
key to select and deselect multiple checkboxes at once.
API Reference
Root
Container for the checkbox group.
Prop | Type | Default |
---|---|---|
defaultValue | string[] | - |
value | string[] | - |
onValueChange | (value: string[]) => void | - |
asChild | boolean | - |
onValidate | (value: string[]) => string | true | string[] | null | undefined | - |
disabled | boolean | - |
invalid | boolean | - |
readOnly | boolean | false |
required | boolean | false |
name | string | - |
orientation | "horizontal" | "vertical" | "vertical" |
Data Attribute | Value |
---|---|
[data-invalid] | Present when invalid. |
[data-disabled] | Present when disabled. |
[data-orientation] | "vertical" | "horizontal" |
Label
Label for the checkbox group.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
Data Attribute | Value |
---|---|
[data-disabled] | Present when disabled. |
List
Container for checkbox items.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
Data Attribute | Value |
---|---|
[data-orientation] | "vertical" | "horizontal" |
[data-invalid] | Present when invalid. |
Item
Individual checkbox item.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
required | boolean | - |
Data Attribute | Value |
---|---|
[data-state] | "checked" | "unchecked" |
[data-disabled] | Present when disabled. |
[data-invalid] | Present when invalid. |
[data-orientation] | "vertical" | "horizontal" |
Indicator
Visual indicator for the checkbox state.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
forceMount | boolean | - |
Data Attribute | Value |
---|---|
[data-state] | "checked" | "unchecked" |
[data-disabled] | Present when disabled. |
Description
Optional description text for the checkbox group.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
announce | boolean | false |
hideOnError | boolean | false |
Data Attribute | Value |
---|---|
[data-disabled] | Present when disabled. |
[data-invalid] | Present when invalid. |
Message
Error or validation message for the checkbox group.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
announce | boolean | false |
Data Attribute | Value |
---|---|
[data-disabled] | Present when disabled. |
[data-invalid] | Present when invalid. |
Accessibility
Keyboard Interactions
Key | Description |
---|---|
Space | Toggles checkbox item. |