2020-08-13 15:18:26 +08:00
## Checkbox
A group of options for multiple choices.
### Basic usage
Checkbox can be used alone to switch between two states.
:::demo 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.
```html
< template >
2021-08-27 20:28:56 +08:00
< div >
< el-checkbox v-model = "checked1" label = "Option 1" > < / el-checkbox >
< el-checkbox v-model = "checked2" label = "Option 2" > < / el-checkbox >
< / div >
< div >
2021-09-04 19:29:28 +08:00
< el-checkbox
v-model="checked3"
label="Option 1"
size="medium"
>< / el-checkbox >
< el-checkbox
v-model="checked4"
label="Option 2"
size="medium"
>< / el-checkbox >
2021-08-27 20:28:56 +08:00
< / div >
< div >
< el-checkbox v-model = "checked5" label = "Option 1" size = "small" > < / el-checkbox >
< el-checkbox v-model = "checked6" label = "Option 2" size = "small" > < / el-checkbox >
< / div >
< div >
< el-checkbox v-model = "checked7" label = "Option 1" size = "mini" > < / el-checkbox >
< el-checkbox v-model = "checked8" label = "Option 2" size = "mini" > < / el-checkbox >
< / div >
2020-08-13 15:18:26 +08:00
< / template >
< script >
export default {
data() {
return {
2021-08-27 20:28:56 +08:00
checked1: true,
checked2: false,
checked3: false,
checked4: false,
checked5: false,
checked6: false,
checked7: false,
checked8: false,
2021-09-04 19:29:28 +08:00
}
},
}
2020-08-13 15:18:26 +08:00
< / script >
2021-06-08 13:15:13 +08:00
<!--
< setup >
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
2021-08-27 20:28:56 +08:00
const checked1 = ref(true);
const checked2 = ref(false);
const checked3 = ref(false);
const checked4 = ref(false);
const checked5 = ref(false);
const checked6 = ref(false);
const checked7 = ref(false);
const checked8 = ref(false);
2021-06-08 13:15:13 +08:00
return {
2021-08-27 20:28:56 +08:00
checked1,
checked2,
checked3,
checked4,
checked5,
checked6,
checked7,
checked8,
2021-06-08 13:15:13 +08:00
};
},
});
< / setup >
-->
2020-08-13 15:18:26 +08:00
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Disabled State
Disabled state for checkbox.
:::demo Set the `disabled` attribute.
```html
< template >
< el-checkbox v-model = "checked1" disabled > Option< / el-checkbox >
< el-checkbox v-model = "checked2" disabled > Option< / el-checkbox >
< / template >
< script >
export default {
data() {
return {
checked1: false,
2021-09-04 19:29:28 +08:00
checked2: true,
}
},
}
2020-08-13 15:18:26 +08:00
< / script >
2021-06-08 13:15:13 +08:00
<!--
< setup >
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const checked1 = ref(false);
const checked2 = ref(true);
return {
checked1,
checked2,
};
},
});
< / setup >
-->
2020-08-13 15:18:26 +08:00
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### 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.
:::demo `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, `label` 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. `label` also corresponds with the element values in the array. It is selected if the specified value exists in the array, and vice versa.
```html
< template >
< el-checkbox-group v-model = "checkList" >
< el-checkbox label = "Option A" > < / el-checkbox >
< el-checkbox label = "Option B" > < / el-checkbox >
< el-checkbox label = "Option C" > < / el-checkbox >
< el-checkbox label = "disabled" disabled > < / el-checkbox >
< el-checkbox label = "selected and disabled" disabled > < / el-checkbox >
< / el-checkbox-group >
< / template >
< script >
export default {
2021-09-04 19:29:28 +08:00
data() {
2020-08-13 15:18:26 +08:00
return {
2021-09-04 19:29:28 +08:00
checkList: ['selected and disabled', 'Option A'],
}
},
}
2020-08-13 15:18:26 +08:00
< / script >
2021-06-08 13:15:13 +08:00
<!--
< setup >
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const checkList = ref(['selected and disabled','Option A']);
return {
checkList,
};
},
});
< / setup >
-->
2020-08-13 15:18:26 +08:00
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Indeterminate
The `indeterminate` property can help you to achieve a 'check all' effect.
:::demo
```html
< template >
2021-09-04 19:29:28 +08:00
< el-checkbox
:indeterminate="isIndeterminate"
v-model="checkAll"
@change ="handleCheckAllChange"
>Check all< /el-checkbox
>
< el-checkbox-group
v-model="checkedCities"
@change ="handleCheckedCitiesChange"
>
< el-checkbox v-for = "city in cities" :label = "city" :key = "city"
>{{city}}< /el-checkbox
>
2020-08-13 15:18:26 +08:00
< / el-checkbox-group >
< / template >
< script >
2021-09-04 19:29:28 +08:00
const cityOptions = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
2020-08-13 15:18:26 +08:00
export default {
data() {
return {
checkAll: false,
checkedCities: ['Shanghai', 'Beijing'],
cities: cityOptions,
2021-09-04 19:29:28 +08:00
isIndeterminate: true,
}
2020-08-13 15:18:26 +08:00
},
methods: {
handleCheckAllChange(val) {
2021-09-04 19:29:28 +08:00
this.checkedCities = val ? cityOptions : []
this.isIndeterminate = false
2020-08-13 15:18:26 +08:00
},
handleCheckedCitiesChange(value) {
2021-09-04 19:29:28 +08:00
let checkedCount = value.length
this.checkAll = checkedCount === this.cities.length
this.isIndeterminate =
checkedCount > 0 & & checkedCount < this.cities.length
},
},
}
2020-08-13 15:18:26 +08:00
< / script >
2021-06-08 13:15:13 +08:00
<!--
< setup >
import { defineComponent, reactive, toRefs } from 'vue';
const cityOptions = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen'];
export default defineComponent({
setup() {
const state = reactive({
checkAll: false,
checkedCities: ['Shanghai', 'Beijing'],
cities: cityOptions,
isIndeterminate: true,
});
const handleCheckAllChange = (val) => {
state.checkedCities = val ? cityOptions : [];
state.isIndeterminate = false;
};
const handleCheckedCitiesChange = (value) => {
const checkedCount = value.length;
state.checkAll = checkedCount === state.cities.length;
state.isIndeterminate = checkedCount > 0 & & checkedCount < state.cities.length ;
};
return {
...toRefs(state),
handleCheckAllChange,
handleCheckedCitiesChange,
};
},
});
< / setup >
-->
2020-08-13 15:18:26 +08:00
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Minimum / Maximum items checked
The `min` and `max` properties can help you to limit the number of checked items.
:::demo
```html
< template >
2021-09-04 19:29:28 +08:00
< el-checkbox-group v-model = "checkedCities" :min = "1" :max = "2" >
< el-checkbox v-for = "city in cities" :label = "city" :key = "city"
>{{city}}< /el-checkbox
>
2020-08-13 15:18:26 +08:00
< / el-checkbox-group >
< / template >
< script >
2021-09-04 19:29:28 +08:00
const cityOptions = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
2020-08-13 15:18:26 +08:00
export default {
data() {
return {
checkedCities: ['Shanghai', 'Beijing'],
2021-09-04 19:29:28 +08:00
cities: cityOptions,
}
},
}
2020-08-13 15:18:26 +08:00
< / script >
2021-06-08 13:15:13 +08:00
<!--
< setup >
import { defineComponent, reactive, toRefs } from 'vue';
const cityOptions = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen'];
export default defineComponent({
setup() {
const state = reactive({
checkedCities: ['Shanghai', 'Beijing'],
cities: cityOptions,
});
return {
...toRefs(state),
};
},
});
< / setup >
-->
2020-08-13 15:18:26 +08:00
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Button style
Checkbox with button styles.
:::demo You just need to change `el-checkbox` element into `el-checkbox-button` element. We also provide `size` attribute.
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
```html
< template >
< div >
< el-checkbox-group v-model = "checkboxGroup1" >
2021-09-04 19:29:28 +08:00
< el-checkbox-button v-for = "city in cities" :label = "city" :key = "city"
>{{city}}< /el-checkbox-button
>
2020-08-13 15:18:26 +08:00
< / el-checkbox-group >
< / div >
< div style = "margin-top: 20px" >
< el-checkbox-group v-model = "checkboxGroup2" size = "medium" >
2021-09-04 19:29:28 +08:00
< el-checkbox-button v-for = "city in cities" :label = "city" :key = "city"
>{{city}}< /el-checkbox-button
>
2020-08-13 15:18:26 +08:00
< / el-checkbox-group >
< / div >
< div style = "margin-top: 20px" >
< el-checkbox-group v-model = "checkboxGroup3" size = "small" >
2021-09-04 19:29:28 +08:00
< el-checkbox-button
v-for="city in cities"
:label="city"
:disabled="city === 'Beijing'"
:key="city"
>{{city}}< /el-checkbox-button
>
2020-08-13 15:18:26 +08:00
< / el-checkbox-group >
< / div >
< div style = "margin-top: 20px" >
< el-checkbox-group v-model = "checkboxGroup4" size = "mini" disabled >
2021-09-04 19:29:28 +08:00
< el-checkbox-button v-for = "city in cities" :label = "city" :key = "city"
>{{city}}< /el-checkbox-button
>
2020-08-13 15:18:26 +08:00
< / el-checkbox-group >
< / div >
< / template >
< script >
2021-09-04 19:29:28 +08:00
const cityOptions = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
2020-08-13 15:18:26 +08:00
export default {
2021-09-04 19:29:28 +08:00
data() {
2020-08-13 15:18:26 +08:00
return {
checkboxGroup1: ['Shanghai'],
checkboxGroup2: ['Shanghai'],
checkboxGroup3: ['Shanghai'],
checkboxGroup4: ['Shanghai'],
2021-09-04 19:29:28 +08:00
cities: cityOptions,
}
},
2020-08-13 15:18:26 +08:00
}
< / script >
2021-06-08 13:15:13 +08:00
<!--
< setup >
import { defineComponent, reactive, toRefs } from 'vue';
const cityOptions = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen'];
export default defineComponent({
setup() {
const state = reactive({
checkboxGroup1: ['Shanghai'],
checkboxGroup2: ['Shanghai'],
checkboxGroup3: ['Shanghai'],
checkboxGroup4: ['Shanghai'],
cities: cityOptions,
});
return {
...toRefs(state),
};
},
});
< / setup >
-->
2020-08-13 15:18:26 +08:00
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### With borders
:::demo The `border` attribute adds a border to Checkboxes.
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
```html
< template >
< div >
< el-checkbox v-model = "checked1" label = "Option1" border > < / el-checkbox >
< el-checkbox v-model = "checked2" label = "Option2" border > < / el-checkbox >
< / div >
< div style = "margin-top: 20px" >
2021-09-04 19:29:28 +08:00
< el-checkbox
v-model="checked3"
label="Option1"
border
size="medium"
>< / el-checkbox >
< el-checkbox
v-model="checked4"
label="Option2"
border
size="medium"
>< / el-checkbox >
2020-08-13 15:18:26 +08:00
< / div >
< div style = "margin-top: 20px" >
< el-checkbox-group v-model = "checkboxGroup1" size = "small" >
< el-checkbox label = "Option1" border > < / el-checkbox >
< el-checkbox label = "Option2" border disabled > < / el-checkbox >
< / el-checkbox-group >
< / div >
< div style = "margin-top: 20px" >
< el-checkbox-group v-model = "checkboxGroup2" size = "mini" disabled >
< el-checkbox label = "Option1" border > < / el-checkbox >
< el-checkbox label = "Option2" border > < / el-checkbox >
< / el-checkbox-group >
< / div >
< / template >
< script >
export default {
2021-09-04 19:29:28 +08:00
data() {
2020-08-13 15:18:26 +08:00
return {
checked1: true,
checked2: false,
checked3: false,
checked4: true,
checkboxGroup1: [],
2021-09-04 19:29:28 +08:00
checkboxGroup2: [],
}
},
2020-08-13 15:18:26 +08:00
}
< / script >
2021-06-08 13:15:13 +08:00
<!--
< setup >
import { defineComponent, reactive, toRefs } from 'vue';
export default defineComponent({
setup() {
const state = reactive({
checked1: true,
checked2: false,
checked3: false,
checked4: true,
checkboxGroup1: [],
checkboxGroup2: [],
});
return {
...toRefs(state),
};
},
});
< / setup >
-->
2020-08-13 15:18:26 +08:00
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Checkbox Attributes
2021-09-04 19:29:28 +08:00
| Attribute | Description | Type | Accepted Values | Default |
| --------------------- | --------------------------------------------------------- | ---------------------------------- | --------------------- | ------- |
| model-value / v-model | binding value | string / number / boolean | — | — |
| label | value of the Checkbox when used inside a `checkbox-group` | string / number / boolean / object | — | — |
| true-label | value of the Checkbox if it's checked | string / number | — | — |
| false-label | 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 | string | medium / small / mini | — |
| name | native 'name' attribute | string | — | — |
| checked | if the Checkbox is checked | boolean | — | false |
| indeterminate | same as `indeterminate` in native checkbox | boolean | — | false |
2020-08-13 15:18:26 +08:00
### Checkbox Events
2021-09-04 19:29:28 +08:00
| Event Name | Description | Parameters |
| ---------- | --------------------------------------- | ----------------- |
| change | triggers when the binding value changes | the updated value |
2020-08-13 15:18:26 +08:00
### Checkbox-group Attributes
2021-09-04 19:29:28 +08:00
| Attribute | Description | Type | Accepted Values | Default |
| --------------------- | ------------------------------------------------- | ------- | --------------------- | ------- |
| model-value / v-model | binding value | array | — | — |
| size | size of checkbox | string | medium / small / mini | — |
| disabled | whether the nesting checkboxes are disabled | boolean | — | false |
| min | minimum number of checkbox checked | number | — | — |
| max | maximum number of checkbox checked | number | — | — |
| text-color | font color when button is active | string | — | #ffffff |
| fill | border and background color when button is active | string | — | #409EFF |
2020-08-13 15:18:26 +08:00
### Checkbox-group Events
2021-09-04 19:29:28 +08:00
| Event Name | Description | Parameters |
| ---------- | --------------------------------------- | ----------------- |
| change | triggers when the binding value changes | the updated value |
2020-08-13 15:18:26 +08:00
### Checkbox-button Attributes
2021-09-04 19:29:28 +08:00
| Attribute | Description | Type | Accepted Values | Default |
| ----------- | --------------------------------------------------------- | ---------------------------------- | --------------- | ------- |
| label | value of the checkbox when used inside a `checkbox-group` | string / number / boolean / object | — | — |
| true-label | value of the checkbox if it's checked | string / number | — | — |
| false-label | 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 |