Checkbox
Used to select multiple options from a set of candidates. Supports regular style, button style, custom icons, and select-all control.
Component Type
Basic Usage
html
<wd-checkbox-group v-model="value">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
<wd-checkbox :name="3" type="square">Option 3</wd-checkbox>
<wd-checkbox :name="4" type="dot">Option 4</wd-checkbox>
</wd-checkbox-group>Standalone Usage
wd-checkbox can be used independently without wd-checkbox-group. Use v-model to bind checked state (default true-value is true, false-value is false). You can also customize checked and unchecked values with true-value / false-value.
html
<wd-checkbox v-model="checked">Agree to terms</wd-checkbox>ts
const checked = ref(false)Custom Checked/Unchecked Value
html
<wd-checkbox v-model="agree" true-value="yes" false-value="no">Agree to terms</wd-checkbox>ts
const agree = ref('no')Component State
Disabled
html
<wd-checkbox-group v-model="value" disabled>
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>
<wd-checkbox-group v-model="value">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2" disabled>Option 2</wd-checkbox>
</wd-checkbox-group>Indeterminate State
html
<wd-checkbox v-model="checked" :indeterminate="indeterminate" @change="indeterminate = false">Indeterminate</wd-checkbox>Readonly
html
<wd-checkbox-group v-model="value" readonly>
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>Component Variant
Right-side Check Icon
html
<wd-checkbox-group v-model="value" placement="right">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>Button Style
html
<wd-checkbox-group v-model="value" type="button">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>Horizontal Layout
html
<wd-checkbox-group v-model="value" direction="horizontal">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>Minimum and Maximum Selection Count
html
<wd-checkbox-group v-model="value" :min="1" :max="3">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
<wd-checkbox :name="3">Option 3</wd-checkbox>
<wd-checkbox :name="4">Option 4</wd-checkbox>
</wd-checkbox-group>Component Style
Custom Checked Color
html
<wd-checkbox-group v-model="value" checked-color="#fa4350">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>Custom Unchecked Color
html
<wd-checkbox-group v-model="value" unchecked-color="#fa4350">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>Custom Icon
html
<wd-checkbox-group v-model="value">
<wd-checkbox :name="1">
Custom Icon
<template #icon="{ isChecked }">
<wd-icon :name="isChecked ? 'star-fill' : 'star'" size="22px" :color="isChecked ? '#fa4350' : '#ccc'" />
</template>
</wd-checkbox>
</wd-checkbox-group>Size
html
<wd-checkbox-group v-model="value" size="large">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
</wd-checkbox-group>Special Style
With Cell
html
<wd-checkbox-group v-model="value" direction="horizontal">
<wd-cell-group border value-align="right">
<wd-cell title="Like" clickable @click="toggle(1)">
<wd-checkbox :name="1" />
</wd-cell>
<wd-cell title="Coin" clickable @click="toggle(2)">
<wd-checkbox :name="2" />
</wd-cell>
<wd-cell title="One-click Triple" clickable @click="toggle(3)">
<wd-checkbox :name="3" />
</wd-cell>
</wd-cell-group>
</wd-checkbox-group>Toggle All
html
<wd-button @click="checkboxGroup?.toggleAll()">Toggle All</wd-button>
<wd-button @click="checkboxGroup?.toggleAll(true)">Select All</wd-button>
<wd-button @click="checkboxGroup?.toggleAll(false)">Unselect All</wd-button>
<wd-button @click="checkboxGroup?.toggleAll({ skipDisabled: true })">Toggle All (Skip Disabled)</wd-button>
<wd-button @click="checkboxGroup?.toggleAll({ checked: true, skipDisabled: true })">Select All (Skip Disabled)</wd-button>
<wd-checkbox-group v-model="value" ref="checkboxGroup">
<wd-checkbox :name="1">Option 1</wd-checkbox>
<wd-checkbox :name="2">Option 2</wd-checkbox>
<wd-checkbox :name="3" disabled>Option 3</wd-checkbox>
<wd-checkbox :name="4">Option 4</wd-checkbox>
</wd-checkbox-group>Checkbox Attributes
| Parameter | Description | Type | Default |
|---|---|---|---|
| v-model | Bound value when used standalone | string | number | boolean | false |
| name | Unique identifier value in CheckboxGroup | string | number | boolean | '' |
| type | Shape type, supports circle / square / button / dot | string | inherited from CheckboxGroup |
| checked-color | Checked color | string | inherited from CheckboxGroup |
| unchecked-color | Unchecked color | string | inherited from CheckboxGroup |
| disabled | Whether disabled | boolean | null | inherited from CheckboxGroup |
| readonly | Whether readonly | boolean | null | inherited from CheckboxGroup |
| indeterminate | Whether indeterminate (highest style priority) | boolean | false |
| true-value | Checked value when used standalone | string | number | boolean | true |
| false-value | Unchecked value when used standalone | string | number | boolean | false |
| size | Size, supports large | string | inherited from CheckboxGroup |
| placement | Check icon position, supports left / right | string | inherited from CheckboxGroup |
| direction | Layout direction, supports horizontal / vertical | string | inherited from CheckboxGroup |
| max-width | Maximum text width | string | - |
| custom-label-class | Custom class for label text | string | - |
| custom-class | Custom class for root node | string | '' |
| custom-style | Custom style for root node | string | '' |
CheckboxGroup Attributes
| Parameter | Description | Type | Default |
|---|---|---|---|
| v-model | Bound value array | Array<string | number | boolean> | [] |
| type | Shape type, supports circle / square / button / dot | string | circle |
| checked-color | Checked color | string | - |
| unchecked-color | Unchecked color | string | - |
| disabled | Whether all options are disabled | boolean | false |
| readonly | Whether all options are readonly | boolean | false |
| min | Minimum selectable count | number | 0 |
| max | Maximum selectable count, 0 means no limit | number | 0 |
| size | Size, supports large | string | - |
| placement | Check icon position, supports left / right | string | left |
| direction | Layout direction, supports horizontal / vertical | string | vertical |
| custom-class | Custom class for root node | string | '' |
| custom-style | Custom style for root node | string | '' |
Checkbox Events
| Event Name | Description | Parameters |
|---|---|---|
| change | Triggered when bound value changes in standalone usage | { value } |
CheckboxGroup Events
| Event Name | Description | Parameters |
|---|---|---|
| change | Triggered when group selected value changes | { value } |
Checkbox Methods
| Method Name | Description | Parameters |
|---|---|---|
| toggle | Toggle current checked state | - |
CheckboxGroup Methods
| Method Name | Description | Parameters |
|---|---|---|
| toggleAll | Batch toggle all options | boolean | { checked?: boolean; skipDisabled?: boolean } |
Checkbox Slots
| name | Description | Parameters |
|---|---|---|
| default | Custom label content | - |
| icon | Custom icon | { isChecked } |
CheckboxGroup Slots
| name | Description | Parameters |
|---|---|---|
| default | Checkbox list content | - |
主题定制
CSS 变量
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 全局配置。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --wot-checkbox-label-margin | $spacing-tight | - |
| --wot-checkbox-color-checked | $primary-6 | 文字与图标距离 |
| --wot-checkbox-icon-size | $n-22 | 选中颜色 |
| --wot-checkbox-unchecked-color | $coolgrey-3 | 图标尺寸 |
| --wot-checkbox-label-font-size | $typography-body-size-main | 未选中图标颜色 |
| --wot-checkbox-label-color | $text-main | 文字字号 |
| --wot-checkbox-label-line-height | $typography-body-line-height-size-main | 文字颜色 |
| --wot-checkbox-opacity-disabled | $opacity-disabled | 文字行高 |
| --wot-checkbox-horizontal-margin | $spacing-zero $spacing-extra-loose $spacing-zero $spacing-zero | 禁用态透明度 |
| --wot-checkbox-button-margin | $spacing-zero $spacing-extra-loose $spacing-extra-loose $spacing-zero | 水平模式多个单选框距离 |
| --wot-checkbox-button-border-width | $stroke-main | 按钮模式多个单选框距离 |
| --wot-checkbox-button-shape-border-radius | $radius-full | 边框宽度 |
| --wot-checkbox-button-shape-size | $n-26 | 按钮模式图标圆角大小 |
| --wot-checkbox-button-font-size | $typography-body-size-main | 按钮模式图标容器大小 |
| --wot-checkbox-button-line-height | $typography-body-line-height-size-main | 按钮模式字号 |
| --wot-checkbox-button-bg | $filled-bottom | 按钮模式行高 |
| --wot-checkbox-button-bg-checked | $filled-oppo | 按钮模式背景颜色 |
| --wot-checkbox-button-icon-size | $n-10 | 按钮模式选中状态背景颜色 |
| --wot-checkbox-button-min-width | calc(74 * #{$n-1}) | 按钮模式图标尺寸 |
| --wot-checkbox-button-max-width | calc(148 * #{$n-1}) | 按钮模式最小宽 |
| --wot-checkbox-button-border-radius | $radius-main | 按钮模式最大宽 |
| --wot-checkbox-button-padding | $padding-extra-tight $padding-extra-loose | 按钮圆角大小 |
| --wot-checkbox-button-icon-color | $icon-white | 按钮模式内边距 |
| --wot-checkbox-button-shape-top | calc(-1 * #{$n-11}) | 按钮模式图标颜色 |
| --wot-checkbox-button-shape-left | calc(-1 * #{$n-9}) | 按钮模式勾角顶部偏移 |
| --wot-checkbox-button-shape-right | calc(-1 * #{$n-9}) | 按钮模式勾角左侧偏移 |
| --wot-checkbox-button-icon-top | calc(13 * #{$n-1}) | 按钮模式勾角右侧偏移 |
| --wot-checkbox-button-icon-right | $n-4 | 按钮模式图标顶部偏移 |
| --wot-checkbox-button-icon-left | $n-4 | 按钮模式图标右侧偏移 |