Checkbox
A binary input that can exist by itself or in a group. When in a group, any number of checkboxes can be checked at a time.
Typical use will involve using v-for to loop through an array of items and output a Checkbox component for each one. Each Checkbox will have the same v-model prop, but different inputValue props and label content.
For a single checkbox, the v-model value will be a boolean true when the checkbox is checked and false when unchecked.
For multiple checkboxes, the v-model value will be an array of the inputValue props of any currently checked checkboxes (or an empty array if no checkboxes are checked).
Demos
Open up the browser console to see events emitted on input.
Single checkbox
A single checkbox does not need an inputValue prop. v-model is bound to a boolean value: true for on, false for off.
<template>
<div>
<p>Checkbox value: {{ checkboxValue }}</p>
<cdx-checkbox v-model="checkboxValue" @update:model-value="onUpdate">
Checked if true
</cdx-checkbox>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import CdxCheckbox from 'vue-components/src/components/checkbox/Checkbox.vue';
export default defineComponent( {
name: 'SingleCheckbox',
components: { CdxCheckbox },
setup() {
const checkboxValue = ref( false );
const onUpdate = ( value: string ): void => {
console.log( 'update:modelValue event: ' + value );
};
return {
checkboxValue,
onUpdate
};
}
} );
</script>
<style scoped>
p {
margin-top: 0;
font-weight: bold;
}
</style>
Checkbox group
For a group of checkboxes, each Checkbox component's v-model will be bound to an array of the inputValue props of the checkboxes that are currently "on".
<template>
<div>
<p>Checkbox value: {{ checkboxValue }}</p>
<cdx-checkbox
v-for="checkbox in checkboxes"
:key="'checkbox-' + checkbox.value"
v-model="checkboxValue"
:input-value="checkbox.value"
:disabled="checkbox.disabled"
:indeterminate="checkbox.indeterminate"
@update:model-value="onUpdate"
>
{{ checkbox.label }}
</cdx-checkbox>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import CdxCheckbox from 'vue-components/src/components/checkbox/Checkbox.vue';
export default defineComponent( {
name: 'CheckboxGroup',
components: { CdxCheckbox },
setup() {
const checkboxValue = ref( [ 'checkbox-2', 'checkbox-6' ] );
const checkboxes = [
{
label: 'Checkbox 1',
value: 'checkbox-1',
disabled: false
},
{
label: 'Checkbox 2 (initially selected)',
value: 'checkbox-2',
disabled: false
},
{
label: 'Checkbox 3, which has a very long label that spans onto a second line to demonstrate what happens when text wraps',
value: 'checkbox-3',
disabled: false
},
{
label: 'Checkbox 4 (indeterminate)',
value: 'checkbox-4',
indeterminate: true,
disabled: false
},
{
label: 'Checkbox 5 (disabled)',
value: 'checkbox-5',
disabled: true
},
{
label: 'Checkbox 6 (initially selected, disabled)',
value: 'checkbox-6',
disabled: true
}
];
const onUpdate = ( value: string ): void => {
console.log( 'update:modelValue event: ' + value );
};
return {
checkboxValue,
checkboxes,
onUpdate
};
}
} );
</script>
<style scoped>
p {
margin-top: 0;
font-weight: bold;
}
</style>
Inline checkboxes
<template>
<div>
<cdx-checkbox
v-for="checkbox in checkboxes"
:key="'checkbox-' + checkbox.value"
v-model="checkboxValue"
:input-value="checkbox.value"
:inline="true"
@update:model-value="onUpdate"
>
{{ checkbox.label }}
</cdx-checkbox>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import CdxCheckbox from 'vue-components/src/components/checkbox/Checkbox.vue';
export default defineComponent( {
name: 'InlineCheckboxes',
components: { CdxCheckbox },
setup() {
const checkboxValue = ref( [ 'checkbox-1' ] );
const checkboxes = [
{
label: 'Checkbox 1',
value: 'checkbox-1'
},
{
label: 'Checkbox 2',
value: 'checkbox-2'
}
];
const onUpdate = ( value: string ): void => {
console.log( 'update:modelValue event: ' + value );
};
return {
checkboxValue,
checkboxes,
onUpdate
};
}
} );
</script>
Indeterminate state
The indeterminate state indicates that a checkbox is neither on nor off. Within this component, this state is purely visual. The parent component must house the logic to set a checkbox to the indeterminate state via this prop (e.g. in the case of a set of nested checkboxes where some boxes are checked and some are not, making the parent checkbox neither fully on nor fully off).
This prop is independent of the value provided by v-model. If indeterminate is set to true, the indeterminate visual state will display, but the value will not be affected. Nor will the value affect the visual state: indeterminate overrides the checked and unchecked visual states. If indeterminate changes to false, the visual state will reflect the current v-model value.
In the example below, all of the checkboxes have their indeterminate prop set to true initially. As a result, they all appear to be in the indeterminate state initially, whether they are checked or not. Checking or unchecking a checkbox will undo the indeterminate state since you have provided a definite value for the checkbox.
<template>
<div>
<p>Checkbox value: {{ checkboxValue }}</p>
<cdx-checkbox
v-for="checkbox in checkboxes"
:key="'checkbox-' + checkbox.value"
v-model="checkboxValue"
:input-value="checkbox.value"
:disabled="checkbox.disabled"
:indeterminate="true"
@update:model-value="onUpdate"
>
{{ checkbox.label }}
</cdx-checkbox>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import CdxCheckbox from 'vue-components/src/components/checkbox/Checkbox.vue';
export default defineComponent( {
name: 'IndeterminateState',
components: { CdxCheckbox },
setup() {
const checkboxValue = ref( [ 'checkbox-2', 'checkbox-4' ] );
const checkboxes = [
{
label: 'Checkbox 1',
value: 'checkbox-1',
disabled: false
},
{
label: 'Checkbox 2 (initially selected)',
value: 'checkbox-2',
disabled: false
},
{
label: 'Checkbox 3 (disabled)',
value: 'checkbox-3',
disabled: true
},
{
label: 'Checkbox 4 (initially selected, disabled)',
value: 'checkbox-4',
disabled: true
}
];
const onUpdate = ( value: string ): void => {
console.log( 'update:modelValue event: ' + value );
};
return {
checkboxValue,
checkboxes,
onUpdate
};
}
} );
</script>
<style scoped>
p {
margin-top: 0;
font-weight: bold;
}
</style>
Usage
Props
| Prop name | Description | Type | Values | Default |
|---|
| modelValue | Value provided by v-model binding in the parent component. | boolean | string[] | number[] | - | false |
| inputValue | HTML "value" attribute to assign to the input.
Required for input groups. | string|number|boolean | - | false |
| disabled | Whether the disabled attribute should be added to the input. | boolean | - | false |
| indeterminate | Whether the indeterminate visual state should be displayed.
This is unrelated to the value provided by v-model, and the indeterminate visual state
will override the checked or unchecked visual state. | boolean | - | false |
| inline | Whether the component should display inline.
By default, display: block is set and a margin exists between
sibling components, for a stacked layout. | boolean | - | false |
Events
| Event name | Properties | Description |
|---|
| update:modelValue | modelValue boolean | string[] | number[] - The new model value | Emitted when modelValue changes. |
Slots
| Name | Description | Bindings |
|---|
| default | Input label content | |