CheckboxGroup
checkbox-groupCoordinates an array of values across a group of checkboxes.
Usage
Basic usage
The child is Hulian Checkbox (each with value), and the group matches members by value.
tsx
<CheckboxGroup defaultValue={["apple"]}>
<Checkbox value="apple" label="Apple" />
<Checkbox value="banana" label="Banana" />
<Checkbox value="cherry" label="Cherry" />
</CheckboxGroup>Horizontal arrangement
orientation=horizontal horizontally and automatically wrap.
tsx
<CheckboxGroup defaultValue={["apple"]} orientation="horizontal">
<Checkbox value="apple" label="Apple" />
<Checkbox value="banana" label="Banana" />
<Checkbox value="cherry" label="Cherry" />
</CheckboxGroup>Disable the entire group
disabled is delivered to all Checkbox in the group.
tsx
<CheckboxGroup defaultValue={["banana"]} disabled>
<Checkbox value="apple" label="Apple" />
<Checkbox value="banana" label="Banana" />
</CheckboxGroup>When to use
Use CheckboxGroup when related checkboxes should share a value array, such as multi-select filters or interest tags. Use Checkbox for one independent Boolean choice, Radio for mutually exclusive options, or Select for dropdown multi-selection. Children are HulianUI Checkbox components with a value; the group matches members by that value.
Import
ts
import { CheckboxGroup } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| value | string[] | — | Controlled array of checked values. |
| defaultValue | string[] | — | Initial checked values when uncontrolled. |
| disabled | boolean | false | Disables every checkbox in the group. |
| orientation | "vertical" | "horizontal" | "vertical" | Layout direction. |
| className | string | — | Additional class name for the root element. |
| aria-label | string | — | Accessible label for the group. |
Events
| Event | Type | Description |
|---|---|---|
| onValueChange | (value: string[]) => void | Called when the checked values change. |
Slots
| Slot | Type | Description |
|---|---|---|
| children | ReactNode | HulianUI Checkbox children, each with a value. |
Usage guidelines
- Every child Checkbox must provide
value, notname. See [[base-ui-checkbox-group-matches-members-by-value-not-name]]: Base UI rc.0 matches group members by each child'svalue. UsingnamemakesdefaultValue,value, andonValueChangefail silently even though the boxes still render.
Related
Playground
<CheckboxGroup defaultValue={["apple"]}>
<Checkbox value="apple" label="Apple" />
<Checkbox value="banana" label="Banana" />
</CheckboxGroup>