组件 · 数据录入
Checkbox 复选框
布尔勾选控件；支持受控与非受控用法，状态不能只靠颜色传达。
使用建议
- 避免：只用颜色区分勾选状态而不提供可访问名称
- 限制：未标 stable
引入
tsx
import { Checkbox, checkboxVariants } from '@selrux/ui/checkbox';演练场
调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。
代码演示
基础用法
配合原生 label 使用。
半选
indeterminate 表示部分选中，常用于全选。
状态与尺寸
disabled、invalid 与 size 六档。
API
属性覆盖：示例用到 6 / 6 个自有属性（100%）
由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。
Checkbox
带样式的复选。ref 仍指向原生 input。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
checked | 受控选中。 | boolean | - |
defaultChecked | 与 checked 互斥。 | boolean | - |
indeterminate | 混合状态。 只影响 aria-checked 与原生 indeterminate。表单仍只提交 checked 对应的值。 | boolean | - |
invalid | 错误状态。 为真时设置 aria-invalid，不渲染错误文案。显式 aria-invalid 优先。 说明节点的 id 由调用方通过 aria-describedby、aria-errormessage 传入。 | boolean | - |
onCheckedChange | 选中变化。 在原生 onChange 之后调用，参数为浏览器已经切换后的 checked。 | ((checked: boolean) => void) | - |
size | 尺寸。省略时使用 ConfigProvider，无配置时为 md。 | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | - |
另有 305 项原生属性与事件继承自 HTMLAttributes / InputHTMLAttributes，原样透传。
导出类型：CheckboxProps、CheckboxSize、CheckboxVariantOptions
函数与常量
| 名称 | 说明 | 签名 / 类型 |
|---|---|---|
checkboxVariants | 组合基础类、尺寸和可选附加类。 | (options?: CheckboxVariantOptions) => string |
无障碍
摘自源码 JSDoc。
- 只影响 aria-checked 与原生 indeterminate。
- 为真时设置 aria-invalid，不渲染错误文案。
- 显式 aria-invalid 优先。
- 说明节点的 id 由调用方通过 aria-describedby、aria-errormessage 传入。