Checkbox 复选框
新粗野主义风格的复选框，基于 reka-ui 的 CheckboxRoot 原语构建，带勾选指示器。
预览
Preview
默认
主要
危险
不确定状态（Minus 图标）
自定义 aria-label
安装
pnpm dlx brutx-vue@latest add checkbox用法
vue
<script setup>
import { ref } from 'vue'
import { Checkbox } from 'brutx-ui-vue'
const checked = ref(false)
</script>
<template>
<div class="flex items-center gap-3">
<Checkbox v-model:checked="checked" />
<span class="text-sm font-bold">Accept terms</span>
</div>
</template>变体
| 变体 | 说明 |
|---|---|
default | 默认背景，标准前景色 |
primary | Primary（珊瑚色）背景 |
secondary | Secondary（薄荷青）背景 |
accent | Accent（黄色）背景 |
danger | Danger（红色）背景 |
vue
<template>
<Checkbox variant="primary" />
</template>尺寸
| 尺寸 | 说明 |
|---|---|
sm | 小尺寸 |
default | 默认尺寸 |
lg | 大尺寸 |
搭配 Label
vue
<script setup>
import { ref } from 'vue'
import { Checkbox, Label } from 'brutx-ui-vue'
const checked = ref(false)
</script>
<template>
<div class="flex items-center gap-3">
<Checkbox v-model:checked="checked" id="terms" />
<Label for="terms">Accept terms and conditions</Label>
</div>
</template>禁用状态
vue
<script setup>
import { Checkbox } from 'brutx-ui-vue'
</script>
<template>
<Checkbox disabled />
</template>不确定状态
将 checked 设置为 'indeterminate' 可展示不确定状态，此时指示器显示 Minus（减号）图标，常用于"部分选中"等层级选择场景。
非受控模式同样支持：<Checkbox defaultValue="indeterminate" /> 初始渲染 Minus 图标且 aria-checked="mixed"。按 reka-ui 语义，用户点击后状态切换为 checked，不会自动回到不确定态。
vue
<script setup>
import { Checkbox } from 'brutx-ui-vue'
</script>
<template>
<Checkbox :checked="'indeterminate'" />
</template>API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
class | string | undefined | undefined | 追加到复选框根交互元素的 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
checked | boolean | "indeterminate" | undefined | undefined | 受控选中状态，可为选中、未选中或 indeterminate；省略时组件使用内部状态。 |
详情声明类型boolean | "indeterminate" | undefined 字面量
默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
defaultValue | boolean | "indeterminate" | undefined | undefined | 非受控模式的初始状态，仅在 checked 未设置时生效。 |
详情声明类型boolean | "indeterminate" | undefined 字面量
默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
disabled | boolean | undefined | false | 禁用复选框交互并传递禁用状态给底层 Reka UI 原语。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
variant | "accent" | "danger" | "default" | "primary" | "secondary" | undefined | "default" | 选择复选框的颜色样式变体。 |
详情声明类型NonNullable<"default" | "primary" | "secondary" | "danger" | "accent" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
size | "default" | "lg" | "sm" | undefined | "default" | 设置复选框及内部状态图标的尺寸。 |
详情声明类型NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
ariaLabel | string | undefined | undefined | 复选框的无障碍名称；未提供时使用本地化默认文案。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
name | string | undefined | undefined | 原生表单字段名；设置后随所属表单提交复选框值。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
value可空 | AcceptableValue | undefined | undefined | 随表单提交的值；传递给 Reka UI 根原语，未设置时使用其原生默认值 on。 |
详情声明类型AcceptableValue | undefined 字面量
默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
required | boolean | undefined | false | 设置原生表单必填状态并传递给底层原语。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/checkbox/Checkbox.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@update:checked | [value: boolean | "indeterminate"] | 选中状态变化时发出新的布尔值或 indeterminate，可与 v-model:checked 配合。 |
详情声明类型[value: boolean | "indeterminate"] 字面量
来源packages/ui/src/components/checkbox/Checkbox.vue | ||
可访问性
- 键盘操作：支持
Space键切换选中状态 - ARIA 属性：Checkbox 默认通过 locale 提供
aria-label（中文为"复选框"），未提供时回退到t('checkbox.check')。当毗邻可见文本已能描述用途时可省略，否则建议通过ariaLabel提供更具体的描述 - 焦点管理：使用
--brutal-ring令牌显示可见聚焦环
vue
<script setup>
import { ref } from 'vue'
import { Checkbox, Label } from 'brutx-ui-vue'
const checked = ref(false)
</script>
<template>
<div class="flex items-center gap-3">
<Checkbox v-model:checked="checked" id="marketing" ariaLabel="接收营销邮件" />
<Label for="marketing">接收营销邮件</Label>
</div>
</template>