CheckboxGroup
checkbox-group让一组复选框共同维护一个值数组
用法
基础用法
子项为瑚琏 Checkbox（各带 value），组按 value 匹配成员。
tsx
<CheckboxGroup defaultValue={["apple"]}>
<Checkbox value="apple" label="苹果" />
<Checkbox value="banana" label="香蕉" />
<Checkbox value="cherry" label="樱桃" />
</CheckboxGroup>横向排列
orientation=horizontal 横排并自动换行。
tsx
<CheckboxGroup defaultValue={["apple"]} orientation="horizontal">
<Checkbox value="apple" label="苹果" />
<Checkbox value="banana" label="香蕉" />
<Checkbox value="cherry" label="樱桃" />
</CheckboxGroup>整组禁用
disabled 下发到组内全部 Checkbox。
tsx
<CheckboxGroup defaultValue={["banana"]} disabled>
<Checkbox value="apple" label="苹果" />
<Checkbox value="banana" label="香蕉" />
</CheckboxGroup>何时用
一组相关复选项，需用一个 value 数组统一管理勾选状态（多选筛选、兴趣标签）。单个独立勾选用 Checkbox；互斥单选用 Radio；下拉式多选用 Select。子项放瑚琏 Checkbox，每个带 value，组按 value 匹配成员。
导入
ts
import { CheckboxGroup } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | string[] | - | 受控：已勾选项的 value 数组 |
| defaultValue | string[] | - | 非受控初始勾选项 |
| disabled | boolean | false | 下发禁用到组内全部 Checkbox |
| orientation | "vertical" ｜ "horizontal" | "vertical" | 排列方向 |
| className | string | - | 透传根节点类名 |
| aria-label | string | - | 组的无障碍标签 |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onValueChange | (value: string[]) => void | 勾选变化回调 |
Slots
| 插槽 | 类型 | 说明 |
|---|---|---|
| children | ReactNode | 子项为瑚琏 Checkbox（每个带 value） |
禁忌 / 坑
- 每个子 Checkbox 必须传
value（不是name）——见 [[base-ui-checkbox-group-matches-members-by-value-not-name]]：Base UI rc.0 CheckboxGroup 按子项value匹配成员，用name会让 defaultValue/value/onValueChange 全部静默失效（框渲染正常但勾选/回调全空，极易误判已装好）。 - 放进
Field时每个子 Checkbox 由自己的label命名，Field的标签命名的是整个组（role=group），description / error 仍到达每一项。不必再手工包 Base UI 的Field.Item。
相关
Playground
<CheckboxGroup defaultValue={["apple"]}>
<Checkbox value="apple" label="苹果" />
<Checkbox value="banana" label="香蕉" />
</CheckboxGroup>