CheckboxGroup
checkbox-group复选组 · Base UI 值数组协调 + 复用瑚琏 Checkbox
用法
基础用法
子项为瑚琏 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 全部静默失效（框渲染正常但勾选/回调全空，极易误判已装好）。
相关
Playground
<CheckboxGroup defaultValue={["apple"]}>
<Checkbox value="apple" label="苹果" />
<Checkbox value="banana" label="香蕉" />
</CheckboxGroup>