一个 React 复选框，采用 Liquid Glass 方块、勾选动画与不确定状态。
Checkbox 渲染玻璃方块、勾选/横线指示器、可选标签与描述，以及用于表单提交的隐藏原生复选框。
方块在未选中时保持玻璃表面；选中后由 --ui-ink 填充，并通过缩放动画显示标记。支持 indeterminate 混合状态。
label 与 description 会渲染在方块右侧，整行都可以点击。未使用 checked 时是非受控组件，可用 defaultChecked 设置初始状态。
用 checked 与 onCheckedChange 控制状态。onCheckedChange 也会收到事件详情。
Two-factor authentication is off.
indeterminate 会把复选框显示为混合状态，并渲染横线标记。它通常用于“全选”父级：当部分子项被选中时设置 indeterminate，全部选中时设置 checked。
提供 xs、sm、md、lg、xl 五种尺寸；标签与描述的字号会随尺寸调整。
disabled 会停止交互并淡化整行；readOnly 保留焦点，但不允许修改选中状态。
Checkbox 渲染带 role="checkbox" 与 aria-checked 的可聚焦元素（默认是 <span>），并包含用于表单提交的隐藏原生复选框。可见的 label 为其命名，description 通过 aria-describedby 关联；显式 ARIA 名称优先。
Space 切换当前控件。indeterminate 会设置 aria-checked="mixed"。必须勾选时请设置 required；表单模式见可访问性指南。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
label | ReactNode | — | 可见标签；未提供 aria-label 或 aria-labelledby 时会成为可访问名称。 |
description | ReactNode | — | 标签下方的说明文字；控件有名称时会通过 aria-describedby 关联。 |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 方块、图标与文字尺寸。 |
checked | boolean | — | 受控的选中状态。 |
defaultChecked | boolean | false | 非受控时的初始选中状态。 |
indeterminate | boolean | false | 混合状态；为 true 时设置 aria-checked="mixed"。 |
onCheckedChange | (checked: boolean, details) => void | — | 选中状态变化时调用。 |
disabled | boolean | false | 禁用交互。 |
readOnly | boolean | false | 只读，不可修改，但仍可聚焦。 |
required | boolean | false | 表单提交前必须选中。 |
name | string | — | 表单字段名。 |
form | string | — | 拥有隐藏输入框的表单 ID。 |
value | string | — | 选中时随表单提交的值。 |
uncheckedValue | string | — | 未选中时随表单提交的值。 |
parent | boolean | false | 是否作为 CheckboxGroup 中一组子复选框的父复选框。 |
id | string | — | 隐藏输入框的 ID；当 nativeButton 为 true 时改为根元素的 ID。 |
inputRef | Ref<HTMLInputElement> | — | 指向隐藏原生输入框的 ref。 |
nativeButton | boolean | false | 是否渲染原生 <button>。 |
render | ReactElement | ((props, state) => ReactElement) | — | 替换根元素。 |
ref | Ref<HTMLElement> | — | 转发到根元素的 ref。 |
className | string | — | 合并到复选框根元素的 Tailwind 类名。 |
style | CSSProperties | — | 内联样式，合并到与 className 相同的元素。 |
ui | { root?: ClassValue; box?: ClassValue; fill?: ClassValue; glass?: ClassValue; overlay?: ClassValue; indicator?: ClassValue; indicatorIcon?: ClassValue; wrapper?: ClassValue; label?: ClassValue; description?: ClassValue } | — | 按 data-slot 组织的内部槽位类名。 |
| 属性 | 说明 |
|---|---|
data-checked | 复选框选中时存在。 |
data-unchecked | 复选框未选中时存在。 |
data-indeterminate | 复选框处于混合状态时存在。 |
data-disabled | 复选框禁用时存在。 |
data-readonly | 复选框只读时存在。 |
data-required | 复选框必填时存在。 |
data-valid | 复选框包裹在 Field 中且有效时存在。 |
data-invalid | 复选框包裹在 Field 中且无效时存在。 |
data-touched | 复选框包裹在 Field 中并被触碰后存在。 |
data-dirty | 复选框包裹在 Field 中且值变化后存在。 |
data-filled | 复选框包裹在 Field 中且选中时存在。 |
data-focused | 复选框包裹在 Field 中且聚焦时存在。 |
data-starting-style | 指示器开始进入动画时存在。 |
data-ending-style | 指示器正在退出动画时存在。 |
data-slot | 标记内部部件（root、box、fill、glass、overlay、indicator、indicator-icon、wrapper、label、description），用于样式选择。 |
组件使用共享玻璃材质。可以在父级调整 --ui-glass-* token，用 className 控制布局，并通过 ui 按 data-slot 调整内部槽位。组件级数值位于 src/theme/checkbox.ts。Token 分层与预设见主题指南。