Checkbox
A group of options for multiple choices.
WARNING
label
act as value
has been deprecated, label
is used only as display text, this action will be removed in 3.0.0, consider switching to new API.
TIP
New API value
has been added in 2.6.0, the examples in the document all use the value
. If you are using a version less than 2.6.0 and using checkbox-group
, please refer to:
<template>
<el-checkbox-group v-model="checkList">
<!-- works when >=2.6.0, recommended ✔️ value not work when <2.6.0 ❌ -->
<el-checkbox label="Option 1" value="Value 1" />
<!-- works when <2.6.0, deprecated act as value when >=3.0.0 -->
<el-checkbox label="Option 2 & Value 2" />
</el-checkbox-group>
</template>
Basic usage
Checkbox can be used alone to switch between two states.
Define v-model
(bind variable) in el-checkbox
. The default value is a Boolean
for single checkbox
, and it becomes true
when selected. Content inside the el-checkbox
tag will become the description following the button of the checkbox.
Disabled State
Disabled state for checkbox.
Set the disabled
attribute.
Checkbox group
It is used for multiple checkboxes which are bound in one group, and indicates whether one option is selected by checking if it is checked.
checkbox-group
element can manage multiple checkboxes in one group by using v-model
which is bound as an Array
. Inside the el-checkbox
element, value
is the value of the checkbox. If no content is nested in that tag, label
will be rendered as the description following the button of the checkbox. value
also corresponds with the element values in the array. It is selected if the specified value exists in the array, and vice versa.
Indeterminate
The indeterminate
property can help you to achieve a 'check all' effect.
Minimum / Maximum items checked
The min
and max
properties can help you to limit the number of checked items.
Button style
Checkbox with button styles.
You just need to change el-checkbox
element into el-checkbox-button
element. We also provide size
attribute.
With borders
The border
attribute adds a border to Checkboxes.
Checkbox API
Checkbox Attributes
Name | Description | Type | Default |
---|---|---|---|
model-value / v-model | binding value | string / number / boolean | — |
value 2.6.0 | value of the Checkbox when used inside a checkbox-group | string / number / boolean / object | — |
label | label of the Checkbox when used inside a checkbox-group . If there's no value, label will act as value | string / number / boolean / object | — |
true-value 2.6.0 | value of the Checkbox if it's checked | string / number | — |
false-value 2.6.0 | value of the Checkbox if it's not checked | string / number | — |
disabled | whether the Checkbox is disabled | boolean | false |
border | whether to add a border around Checkbox | boolean | false |
size | size of the Checkbox | enum | — |
name | native 'name' attribute | string | — |
checked | if the Checkbox is checked | boolean | false |
indeterminate | Set indeterminate state, only responsible for style control | boolean | false |
validate-event | whether to trigger form validation | boolean | true |
tabindex | input tabindex | string / number | — |
id | input id | string | — |
aria-controls a11y 2.7.2 | same as aria-controls, takes effect when indeterminate is true | string | — |
true-label deprecated | value of the Checkbox if it's checked | string / number | — |
false-label deprecated | value of the Checkbox if it's not checked | string / number | — |
controls a11y deprecated | same as aria-controls, takes effect when indeterminate is true | string | — |
Checkbox Events
Name | Description | Type |
---|---|---|
change | triggers when the binding value changes | Function |
Checkbox Slots
Name | Description |
---|---|
default | customize default content |
CheckboxGroup API
CheckboxGroup Attributes
Name | Description | Type | Default |
---|---|---|---|
model-value / v-model | binding value | object | [] |
size | size of checkbox | enum | — |
disabled | whether the nesting checkboxes are disabled | boolean | false |
min | minimum number of checkbox checked | number | — |
max | maximum number of checkbox checked | number | — |
aria-label a11y 2.7.2 | native aria-label attribute | string | — |
text-color | font color when button is active | string | #ffffff |
fill | border and background color when button is active | string | #409eff |
tag | element tag of the checkbox group | string | div |
validate-event | whether to trigger form validation | boolean | true |
label a11y deprecated | native aria-label attribute | string | — |
CheckboxGroup Events
Name | Description | Type |
---|---|---|
change | triggers when the binding value changes | Function |
CheckboxGroup Slots
Name | Description | Subtags |
---|---|---|
default | customize default content | Checkbox / Checkbox-button |
CheckboxButton API
CheckboxButton Attributes
Name | Description | Type | Default |
---|---|---|---|
value 2.6.0 | value of the checkbox when used inside a checkbox-group | string / number / boolean / object | — |
label | label of the checkbox when used inside a checkbox-group . If there's no value, label will act as value | string / number / boolean / object | — |
true-value 2.6.0 | value of the checkbox if it's checked | string / number | — |
false-value 2.6.0 | value of the checkbox if it's not checked | string / number | — |
disabled | whether the checkbox is disabled | boolean | false |
name | native 'name' attribute | string | — |
checked | if the checkbox is checked | boolean | false |
true-label deprecated | value of the checkbox if it's checked | string / number | — |
false-label deprecated | value of the checkbox if it's not checked | string / number | — |
CheckboxButton Slots
Name | Description |
---|---|
default | customize default content |