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:

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

Options attribute 2.11.2 ​

Shortcut from basic el-checkbox-group usage. You can customize the alias of the options through the props attribute.

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 ​

NameDescriptionTypeDefault
model-value / v-modelbinding valuestring / number / boolean—
value 2.6.0value of the Checkbox when used inside a checkbox-groupstring / number / boolean / object—
labellabel of the Checkbox when used inside a checkbox-group. If there's no value, label will act as valuestring / number / boolean / object—
true-value 2.6.0value of the Checkbox if it's checkedstring / number—
false-value 2.6.0value of the Checkbox if it's not checkedstring / number—
disabledwhether the Checkbox is disabledbooleanfalse
borderwhether to add a border around Checkboxbooleanfalse
sizesize of the Checkboxenum—
namenative 'name' attributestring—
checkedif the Checkbox is checkedbooleanfalse
indeterminateSet indeterminate state, only responsible for style controlbooleanfalse
validate-eventwhether to trigger form validationbooleantrue
tabindexinput tabindexstring / number—
idinput idstring—
aria-controls a11y 2.7.2same as aria-controls, takes effect when indeterminate is truestring—
aria-label a11ynative aria-label attributestring—
true-label deprecatedvalue of the Checkbox if it's checkedstring / number—
false-label deprecatedvalue of the Checkbox if it's not checkedstring / number—
controls a11y deprecatedsame as aria-controls, takes effect when indeterminate is truestring—

Checkbox Events ​

NameDescriptionType
changetriggers when the binding value changesFunction

Checkbox Slots ​

NameDescription
defaultcustomize default content

CheckboxGroup API ​

CheckboxGroup Attributes ​

NameDescriptionTypeDefault
model-value / v-modelbinding valuearray[]
sizesize of checkboxenum—
disabledwhether the nesting checkboxes are disabledbooleanfalse
minminimum number of checkbox checkednumber—
maxmaximum number of checkbox checkednumber—
aria-label a11y 2.7.2native aria-label attributestring—
text-colorfont color when button is activestring#ffffff
fillborder and background color when button is activestring#409eff
tagelement tag of the checkbox groupstringdiv
validate-eventwhether to trigger form validationbooleantrue
label a11y deprecatednative aria-label attributestring—
options 2.11.2data of the options, the key of value and label and disabled can be customize by propsarray—
props 2.11.2configuration optionsobject{value: 'value', label: 'label', disabled: 'disabled'}
type 2.11.5component type to render options (e.g. 'button')enum'checkbox'

CheckboxGroup Events ​

NameDescriptionType
changetriggers when the binding value changesFunction

CheckboxGroup Slots ​

NameDescriptionSubtags
defaultcustomize default contentCheckbox / Checkbox-button

CheckboxButton API ​

CheckboxButton Attributes ​

NameDescriptionTypeDefault
value 2.6.0value of the checkbox when used inside a checkbox-groupstring / number / boolean / object—
labellabel of the checkbox when used inside a checkbox-group. If there's no value, label will act as valuestring / number / boolean / object—
true-value 2.6.0value of the checkbox if it's checkedstring / number—
false-value 2.6.0value of the checkbox if it's not checkedstring / number—
disabledwhether the checkbox is disabledbooleanfalse
namenative 'name' attributestring—
checkedif the checkbox is checkedbooleanfalse
true-label deprecatedvalue of the checkbox if it's checkedstring / number—
false-label deprecatedvalue of the checkbox if it's not checkedstring / number—

CheckboxButton Slots ​

NameDescription
defaultcustomize default content

Source ​

Component • Style • Docs

Contributors ​