Checkbox 复选框

新粗野主义风格的复选框，基于 reka-ui 的 CheckboxRoot 原语构建，带勾选指示器。

预览

Preview

默认

主要

危险

不确定状态（Minus 图标）

自定义 aria-label

安装

pnpm dlx brutx-vue@latest add checkbox

用法

<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（红色）背景

<template>
    <Checkbox variant="primary" />
</template>

尺寸

尺寸	说明
sm	小尺寸
default	默认尺寸
lg	大尺寸

搭配 Label

<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>

禁用状态

<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，不会自动回到不确定态。

<script setup>
import { Checkbox } from 'brutx-ui-vue'
</script>

<template>
    <Checkbox :checked="'indeterminate'" />
</template>

Props

属性	类型	默认值	说明
checked	boolean | 'indeterminate'	—	选中状态；不传时组件处于非受控模式
defaultValue	boolean | 'indeterminate'	—	非受控模式下的初始选中状态；仅在 checked 为 undefined 时生效
disabled	boolean	false	是否禁用
variant	'default' | 'primary' | 'secondary' | 'accent' | 'danger'	'default'	颜色变体
size	'sm' | 'default' | 'lg'	'default'	尺寸
ariaLabel	string	locale 默认值（checkbox.check）	无障碍标签
name	string	—	表单字段名；提供时渲染隐藏 input，随所属 <form> 以 name/value 提交
value	string | number | bigint | object | null	'on'	随 form 提交的值
required	boolean	false	原生表单必填标记，透传到隐藏 input
class	string	—	自定义样式类

受控与非受控： 不传 checked（或为 undefined）时组件由内部状态维护选中值，点击后通过 update:checked 通知外部，可用 defaultValue 声明初始态；一旦显式传入 checked，组件进入受控模式，选中值以 prop 为准。

事件

事件	参数	说明
update:checked	boolean | 'indeterminate'	选中状态变化时触发，支持 v-model:checked 双向绑定

可访问性

• 键盘操作：支持 Space 键切换选中状态
• ARIA 属性：Checkbox 默认通过 locale 提供 aria-label（中文为"复选框"），未提供时回退到 t('checkbox.check')。当毗邻可见文本已能描述用途时可省略，否则建议通过 ariaLabel 提供更具体的描述
• 焦点管理：使用 --brutal-ring 令牌显示可见聚焦环

<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>