CodexCheckbox
A binary input that can be standalone or in a multiselect 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.
Checkbox value: false
| Name | Value |
|---|---|
| View | |
Reading direction | |
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".
Checkbox group value: [ "checkbox-2", "checkbox-6" ]
Inline checkboxes
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.
Checkbox group value: [ "checkbox-2", "checkbox-4" ]
Form field
A single Checkbox or group of Checkboxes can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.
When building a checkbox field, always set isFieldset to true, even for a single Checkbox, to ensure proper accessibility support.
Usage
Props
| Prop name | Description | Type | Default |
|---|---|---|---|
modelValue | Value of the checkbox or checkbox group. 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 |
CSS-only version
Markup structure
Checkbox group
Native attributes of the <input> element can be used. For example:
- Add the
checkedattribute to the<input>element if it should be selected initially. - Add the
indeterminateattribute to the<input>element if it should appear to be in an indeterminate state. - Add the
disabledattribute to the<input>element if it should be disabled.
Inline checkboxes
Add the cdx-checkbox--inline class to the root element to get an inline layout.