Skip to content
On this page

Checkbox

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

NameValue
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 nameDescriptionTypeDefault
modelValueValue of the checkbox or checkbox group.

Provided by v-model binding in the parent component.
boolean|string[]|number[]false
inputValueHTML "value" attribute to assign to the input.

Required for input groups.
string|number|booleanfalse
disabledWhether the disabled attribute should be added to the input.booleanfalse
indeterminateWhether 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.
booleanfalse
inlineWhether the component should display inline.

By default, display: block is set and a margin exists between sibling components, for a stacked layout.
booleanfalse

Events

Event namePropertiesDescription
update:modelValuemodelValue boolean|string[]|number[] - The new model valueEmitted when modelValue changes.

Slots

NameDescriptionBindings
defaultInput label content

CSS-only version

Markup structure

Checkbox group

Native attributes of the <input> element can be used. For example:

  • Add the checked attribute to the <input> element if it should be selected initially.
  • Add the indeterminate attribute to the <input> element if it should appear to be in an indeterminate state.
  • Add the disabled attribute 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.