Documentation Index
Fetch the complete documentation index at: https://mintlify.com/mui/base-ui/llms.txt
Use this file to discover all available pages before exploring further.
Provides a shared state to a series of checkboxes.
import { CheckboxGroup } from '@base-ui/react/checkbox-group';
Basic Usage
import { Checkbox } from '@base-ui/react/checkbox-group';
<CheckboxGroup value={['option1']} onValueChange={(value) => console.log(value)}>
<Checkbox.Root value="option1">
<Checkbox.Indicator />
</Checkbox.Root>
<Checkbox.Root value="option2">
<Checkbox.Indicator />
</Checkbox.Root>
<Checkbox.Root value="option3">
<Checkbox.Indicator />
</Checkbox.Root>
</CheckboxGroup>
Key Features
- Manages state for multiple checkboxes
- Controlled and uncontrolled modes
- Support for parent checkbox (select all)
- Works with Field component for validation
- Accessible with proper ARIA attributes
Key Props
Type: string[]
Names of the checkboxes in the group that should be ticked. Use with onValueChange for controlled mode.
const [value, setValue] = React.useState(['option1', 'option2']);
<CheckboxGroup value={value} onValueChange={setValue}>
{/* checkboxes */}
</CheckboxGroup>
defaultValue
Type: string[]
Names of the checkboxes in the group that should be initially ticked. Use for uncontrolled mode.
<CheckboxGroup defaultValue={['option1']}>
{/* checkboxes */}
</CheckboxGroup>
onValueChange
Type: (value: string[], eventDetails: ChangeEventDetails) => void
Event handler called when a checkbox in the group is ticked or unticked.
allValues
Type: string[]
Names of all checkboxes in the group. Use this when creating a parent checkbox.
<CheckboxGroup allValues={['option1', 'option2', 'option3']}>
<Checkbox.Root parent>
<Checkbox.Indicator />
</Checkbox.Root>
{/* child checkboxes */}
</CheckboxGroup>
disabled
Type: boolean
Default: false
Whether the component should ignore user interaction.
Styling
<CheckboxGroup className="space-y-2">
<div className="flex items-center gap-2">
<Checkbox.Root value="option1" className="w-5 h-5 border-2 rounded">
<Checkbox.Indicator />
</Checkbox.Root>
<label>Option 1</label>
</div>
<div className="flex items-center gap-2">
<Checkbox.Root value="option2" className="w-5 h-5 border-2 rounded">
<Checkbox.Indicator />
</Checkbox.Root>
<label>Option 2</label>
</div>
</CheckboxGroup>
<CheckboxGroup className={styles.group}>
<div className={styles.item}>
<Checkbox.Root value="option1">
<Checkbox.Indicator />
</Checkbox.Root>
<label>Option 1</label>
</div>
</CheckboxGroup>
.group {
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.item {
display: flex;
align-items: center;
gap: 0.5rem;
}
Common Patterns
With Labels
import { Field } from '@base-ui/react/checkbox-group';
const options = [
{ value: 'react', label: 'React' },
{ value: 'vue', label: 'Vue' },
{ value: 'angular', label: 'Angular' },
];
<Field.Root>
<Field.Label>Select frameworks</Field.Label>
<CheckboxGroup>
{options.map((option) => (
<div key={option.value} className="flex items-center gap-2">
<Checkbox.Root value={option.value}>
<Checkbox.Indicator />
</Checkbox.Root>
<label>{option.label}</label>
</div>
))}
</CheckboxGroup>
</Field.Root>
Select All
const allOptions = ['option1', 'option2', 'option3'];
<CheckboxGroup allValues={allOptions}>
<div className="flex items-center gap-2 mb-2 pb-2 border-b">
<Checkbox.Root parent>
<Checkbox.Indicator />
</Checkbox.Root>
<label className="font-semibold">Select All</label>
</div>
{allOptions.map((option) => (
<div key={option} className="flex items-center gap-2">
<Checkbox.Root value={option}>
<Checkbox.Indicator />
</Checkbox.Root>
<label>{option}</label>
</div>
))}
</CheckboxGroup>
With Validation
import { Field, Form } from '@base-ui/react/checkbox-group';
<Form.Root>
<Field.Root name="interests" validationMode="onChange">
<Field.Label>Select your interests</Field.Label>
<CheckboxGroup>
<Checkbox.Root value="coding">
<Checkbox.Indicator />
</Checkbox.Root>
<Checkbox.Root value="design">
<Checkbox.Indicator />
</Checkbox.Root>
</CheckboxGroup>
<Field.Error />
</Field.Root>
</Form.Root>