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.

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
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 valueobject[]
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

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

ComponentStyleDocs

Contributors