Checkbox
checkbox复选框 · 三态(含半选) + Base UI
用法
基础用法
label 渲染盒右文案并原生关联，点击文字也可切换。
tsx
<Checkbox label="同意条款" />默认选中
非受控写法用 defaultChecked 预设勾选。
tsx
<Checkbox defaultChecked label="记住我" />三态：半选
indeterminate 渲染横杠，常用于「全选」父项。
tsx
<>
<Checkbox indeterminate label="半选" />
<Checkbox defaultChecked label="已选" />
<Checkbox label="未选" />
</>禁用态
disabled 降透明度并屏蔽交互（选中态同样可禁用）。
tsx
<>
<Checkbox disabled label="禁用" />
<Checkbox disabled defaultChecked label="禁用已选" />
</>配合 Field
放进 Field 内自动串联标签与错误信息。
必须勾选才能继续
tsx
<Field label="服务条款" error="必须勾选才能继续" className="w-72">
<Checkbox label="我已阅读并同意" />
</Field>何时用
单个布尔勾选（同意条款、记住我），或带半选（indeterminate）的「全选」父框。多个互相协调的复选项用 CheckboxGroup 包裹（值数组统一管理）；二选一的开关用 Switch；互斥单选用 Radio。
导入
ts
import { Checkbox } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| checked | boolean | — | 受控勾选态 |
| defaultChecked | boolean | — | 非受控初始勾选态 |
| indeterminate | boolean | false | 第三态：半选（Base UI 原生 indeterminate） |
| disabled | boolean | false | 禁用 |
| required | boolean | false | 必填 |
| name | string | — | 表单字段名 |
| value | string | — | 表单值；放进 CheckboxGroup 时按此 value 匹配成员 |
| id | string | — | 关联 label 的 id |
| className | string | — | 落在 Checkbox.Root |
| tabIndex | number | — | 透传到 Checkbox.Root（树场景置 -1 退出 Tab 序，焦点由容器 roving 接管） |
| aria-label | string | — | 无 label 时的无障碍标签 |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onCheckedChange | (checked: boolean) => void | 勾选变化回调（瑚琏收敛签名，丢 eventDetails） |
Slots
| 插槽 | 类型 | 说明 |
|---|---|---|
| label | ReactNode | 盒右 inline label（<label> 原生关联） |
禁忌 / 坑
- 放进 CheckboxGroup 时必须给每个 Checkbox 传
value（不是name）——见 [[base-ui-checkbox-group-matches-members-by-value-not-name]]：Base UI rc.0 按value匹配组成员，传name会让 defaultValue/value/onValueChange 全部静默失效（框照常渲染但勾选/回调全空）。 indeterminate是独立第三态，点击后通常应手动消解为确定态（setIndeterminate(false)）。
相关
Playground
<Checkbox label="同意条款" />