CheckboxGroup (复选框组)

数组 v-model 的多选表单字段:classic / pill / card 三种外观,可设数量上限并在被拦下时发出 invalid。

基础用法

v-model 是一个真正的数组 —— 这也是它和一排 KunCheckBox 的区别:一个多选表单字段,而不是几个各自为政的布尔值。

支持平台

已选:windows

Basic.vue

三种外观

classic
pill
card
Variants.vue

卡片 + 图标

邮件通知
Card.vue

数量上限

到达 max 后未选中的项不再可选,已选中的仍可取消;被拦下的点击会发出 invalid 事件。

题材标签(最多 3 个)

Max.vue

禁用

单个选项禁用
整组禁用
Disabled.vue

属性

属性类型默认值说明
modelValue *KunCheckBoxGroupValue[]The selected values, two-way bound with `v-model`. Required: a checkbox group with no model has nothing to select into.
options *readonly KunCheckBoxGroupOption<KunCheckBoxGroupValue>[]The selectable options. `value` is what lands in the model; `label` is shown, and `description` / `icon` / `disabled` are optional per option.
ariaLabelstring""Accessible name for the group. Not needed when `label` is set — that becomes the group's name.
classNamestring""Extra classes, merged after the component's own classes so yours wins the conflict — KunUI's `rounded-kun-*` / `shadow-kun-*` scales included.
colorKunUIColor"primary"Semantic colour of the selected state and the focus ring.
disabledbooleanfalseBlocks the whole group and dims it. A single option is disabled through its own `disabled`.
errorstring""Error message below the group.
hideIndicatorbooleanfalse`card` variant only: drop the checkbox-box indicator, signal selection with the tinted border/fill alone (the icon-card look).
labelstring""Visible label above the group, wired to it with `aria-labelledby`.
maxnumberCap on how many options can be selected at once. A click that would exceed it is blocked and emits `invalid` with `'max-reached'` (already-selected options can still be toggled off).
orientationKunCheckBoxGroupOrientation"vertical"Stack the options vertically, or wrap them in a row.
roundedKunUIRounded`card` variant only — it is the only variant with a surface of its own to round. `classic` is a box plus a label, and `pill` is a pill by definition; both ignore this.
sizeKunUISize"md"Box, icon and text scale — shared with KunCheckBox and KunRadioGroup, so equal `size` renders identically across the three.
variantKunCheckBoxGroupVariant"classic"Presentation: `classic` box + label, `pill` filter chips, `card` bordered cards with an optional icon.

事件

事件回调参数说明
changevalue: KunCheckBoxGroupValue[]The new selection, after a user toggle only — a programmatic `v-model` write does not emit it.
invalidreason: "max-reached"A click was blocked because it would exceed `max`.
update:modelValuevalue: KunCheckBoxGroupValue[]