CheckboxGroupUpdated
A checkbox group component for managing multiple checkbox selections
Import
import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react';Usage
Anatomy
Import the CheckboxGroup component and access all parts using dot notation.
import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react';
export default () => (
<CheckboxGroup name="interests">
<Label />
<Description /> {/* Optional */}
<Checkbox value="option1">
<Checkbox.Content>
<Checkbox.Control>
<Checkbox.Indicator />
</Checkbox.Control>
Label {/* plain text — the clickable label */}
</Checkbox.Content>
<Description /> {/* Optional per-checkbox help text */}
</Checkbox>
<FieldError /> {/* Optional */}
</CheckboxGroup>
);In Surface
When used inside a Surface component, use variant="secondary" to apply the lower emphasis variant suitable for surface backgrounds.
With Custom Indicator
Indeterminate
Controlled
Validation
Disabled
Features and Add-ons Example
Custom Render Function
Styling
Passing Tailwind CSS classes
You can customize the CheckboxGroup component:
import { CheckboxGroup, Checkbox, Label } from '@heroui/react';
function CustomCheckboxGroup() {
return (
<CheckboxGroup className="gap-4" name="custom">
<Checkbox value="option1">
<Checkbox.Content>
<Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
<Checkbox.Indicator className="text-white" />
</Checkbox.Control>
Option 1
</Checkbox.Content>
</Checkbox>
</CheckboxGroup>
);
}Customizing the component classes
To customize the CheckboxGroup component classes, you can use the @layer components directive.
Learn more.
@layer components {
.checkbox-group {
@apply flex flex-col gap-2;
}
}HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.
CSS Classes
The CheckboxGroup component uses these CSS classes (View source styles):
.checkbox-group- Base checkbox group container
API Reference
CheckboxGroup Props
Inherits from React Aria CheckboxGroup.
| Prop | Type | Default | Description |
|---|---|---|---|
value | string[] | - | The current selected values (controlled) |
defaultValue | string[] | - | The default selected values (uncontrolled) |
onChange | (value: string[]) => void | - | Handler called when the selected values change |
isDisabled | boolean | false | Whether the checkbox group is disabled |
isRequired | boolean | false | Whether the checkbox group is required |
isReadOnly | boolean | false | Whether the checkbox group is read only |
isInvalid | boolean | false | Whether the checkbox group is in an invalid state |
name | string | - | The name of the checkbox group, used when submitting an HTML form |
children | React.ReactNode | (values: CheckboxGroupRenderProps) => React.ReactNode | - | Checkbox group content or render prop |
render | DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps> | - | Overrides the default DOM element with a custom render function. |
CheckboxGroupRenderProps
When using the render prop pattern, these values are provided:
| Prop | Type | Description |
|---|---|---|
value | string[] | The currently selected values |
isDisabled | boolean | Whether the checkbox group is disabled |
isReadOnly | boolean | Whether the checkbox group is read only |
isInvalid | boolean | Whether the checkbox group is in an invalid state |
isRequired | boolean | Whether the checkbox group is required |
