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.

Configurable ​

<cdx-checkbox v-model="checkboxValue" />

status

disabled

indeterminate

Reading direction

Single checkbox with label and description ​

Always include label text via the default slot. You can also add description text via the #description slot.

A single checkbox does not need an inputValue prop. v-model is bound to a boolean value: true for checked, false for unchecked.

<template>
	<p class="cdx-docs-demo-text">
		Checkbox value: {{ checkboxValue }}
	</p>

	<cdx-checkbox v-model="checkboxValue" @update:model-value="onUpdate">
		Send password reset emails only when both email address and username are provided.
		<template #description>
			This improves privacy and helps prevent unsolicited emails.
		</template>
	</cdx-checkbox>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxCheckbox } from '@wikimedia/codex';

export default defineComponent( {
	name: 'CheckboxWithDescription',
	components: { CdxCheckbox },
	setup() {
		const checkboxValue = ref( false );

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkboxValue,
			onUpdate
		};
	}
} );
</script>

<template>
	<p class="cdx-docs-demo-text">
		Checkbox value: {{ checkboxValue }}
	</p>

	<cdx-checkbox v-model="checkboxValue" @update:model-value="onUpdate">
		Send password reset emails only when both email address and username are provided.
		<template #description>
			This improves privacy and helps prevent unsolicited emails.
		</template>
	</cdx-checkbox>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxCheckbox } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'CheckboxWithDescription',
	components: { CdxCheckbox },
	setup() {
		const checkboxValue = ref( false );

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkboxValue,
			onUpdate
		};
	}
} );
</script>

Reading direction

Form field ​

When used in a form, 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 accessibility support. This wraps the group in a <fieldset> element and labels it with an associated <legend>.

If using a Checkbox or Checkbox group outside of a form, follow the instructions in the next demo.

<template>
	<cdx-field :is-fieldset="true">
		<cdx-checkbox
			v-for="checkbox in checkboxes"
			:key="'checkbox-' + checkbox.value"
			v-model="checkboxValue"
			:input-value="checkbox.value"
		>
			{{ checkbox.label }}
		</cdx-checkbox>
		<template #label>
			Discussion pages
		</template>
		<template #description>
			These options are provided for the Discussion Tools Beta Feature.
		</template>
		<template #help-text>
			Learn more about these features at the <a href="#">feature summary</a>.
			These tools require JavaScript to be enabled in your browser.
		</template>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxCheckbox, CdxField } from '@wikimedia/codex';

export default defineComponent( {
	name: 'CheckboxField',
	components: { CdxCheckbox, CdxField },
	setup() {
		const checkboxValue = ref( [ 'quickReply', 'quickTopic' ] );
		const checkboxes = [
			{
				label: 'Enable quick replying',
				value: 'quickReply'
			},
			{
				label: 'Enable quick topic adding',
				value: 'quickTopic'
			},
			{
				label: 'Automatically subscribe to topics',
				value: 'autoSubscribe'
			}
		];

		return {
			checkboxValue,
			checkboxes
		};
	}
} );
</script>

<template>
	<cdx-field :is-fieldset="true">
		<cdx-checkbox
			v-for="checkbox in checkboxes"
			:key="'checkbox-' + checkbox.value"
			v-model="checkboxValue"
			:input-value="checkbox.value"
		>
			{{ checkbox.label }}
		</cdx-checkbox>
		<template #label>
			Discussion pages
		</template>
		<template #description>
			These options are provided for the Discussion Tools Beta Feature.
		</template>
		<template #help-text>
			Learn more about these features at the <a href="#">feature summary</a>.
			These tools require JavaScript to be enabled in your browser.
		</template>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxCheckbox, CdxField } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'CheckboxField',
	components: { CdxCheckbox, CdxField },
	setup() {
		const checkboxValue = ref( [ 'quickReply', 'quickTopic' ] );
		const checkboxes = [
			{
				label: 'Enable quick replying',
				value: 'quickReply'
			},
			{
				label: 'Enable quick topic adding',
				value: 'quickTopic'
			},
			{
				label: 'Automatically subscribe to topics',
				value: 'autoSubscribe'
			}
		];

		return {
			checkboxValue,
			checkboxes
		};
	}
} );
</script>

Checkbox group ​

For a group of related checkboxes, each Checkbox component's v-model will be bound to an array of the inputValue props of the checkboxes that are currently "on".

This demo shows what to do when using a Checkbox group outside of a form:

1. Wrap the group in an element with role="group"
2. Connect the group with a label via the aria-labelledby attribute

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Checkbox group value: {{ checkboxValue }}
		</p>

		<div role="group" aria-labelledby="cdx-demo-checkbox-group-label">
			<cdx-label id="cdx-demo-checkbox-group-label">
				Checkbox group demo
			</cdx-label>

			<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>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxCheckbox, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'CheckboxGroup',
	components: { CdxCheckbox, CdxLabel },
	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
			}
		];

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkboxValue,
			checkboxes,
			onUpdate
		};
	}
} );
</script>

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Checkbox group value: {{ checkboxValue }}
		</p>

		<div role="group" aria-labelledby="cdx-demo-checkbox-group-label">
			<cdx-label id="cdx-demo-checkbox-group-label">
				Checkbox group demo
			</cdx-label>

			<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>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxCheckbox, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'CheckboxGroup',
	components: { CdxCheckbox, CdxLabel },
	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
			}
		];

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkboxValue,
			checkboxes,
			onUpdate
		};
	}
} );
</script>

Inline checkboxes ​

Use the inline prop to get an inline layout.

<template>
	<div>
		<cdx-checkbox
			v-model="checkbox1Value"
			input-value="checkbox-1"
			:inline="true"
			@update:model-value="onUpdate"
		>
			Checkbox 1
		</cdx-checkbox>
		<cdx-checkbox
			v-model="checkbox2Value"
			input-value="checkbox-2"
			:inline="true"
			@update:model-value="onUpdate"
		>
			Checkbox 2
		</cdx-checkbox>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxCheckbox } from '@wikimedia/codex';

export default defineComponent( {
	name: 'InlineCheckboxes',
	components: { CdxCheckbox },
	setup() {
		const checkbox1Value = ref( true );
		const checkbox2Value = ref( false );

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkbox1Value,
			checkbox2Value,
			onUpdate
		};
	}
} );
</script>

<template>
	<div>
		<cdx-checkbox
			v-model="checkbox1Value"
			input-value="checkbox-1"
			:inline="true"
			@update:model-value="onUpdate"
		>
			Checkbox 1
		</cdx-checkbox>
		<cdx-checkbox
			v-model="checkbox2Value"
			input-value="checkbox-2"
			:inline="true"
			@update:model-value="onUpdate"
		>
			Checkbox 2
		</cdx-checkbox>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxCheckbox } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'InlineCheckboxes',
	components: { CdxCheckbox },
	setup() {
		const checkbox1Value = ref( true );
		const checkbox2Value = ref( false );

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkbox1Value,
			checkbox2Value,
			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 class="cdx-docs-demo-text">
			Checkbox group value: {{ checkboxValue }}
		</p>

		<cdx-field :is-fieldset="true" :hide-label="true">
			<template #label>
				Indeterminate checkbox demos
			</template>
			<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>
		</cdx-field>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxCheckbox, CdxField } from '@wikimedia/codex';

export default defineComponent( {
	name: 'IndeterminateState',
	components: { CdxCheckbox, CdxField },
	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
			}
		];

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkboxValue,
			checkboxes,
			onUpdate
		};
	}
} );
</script>

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Checkbox group value: {{ checkboxValue }}
		</p>

		<cdx-field :is-fieldset="true" :hide-label="true">
			<template #label>
				Indeterminate checkbox demos
			</template>
			<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>
		</cdx-field>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxCheckbox, CdxField } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'IndeterminateState',
	components: { CdxCheckbox, CdxField },
	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
			}
		];

		function onUpdate( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value:', value );
		}

		return {
			checkboxValue,
			checkboxes,
			onUpdate
		};
	}
} );
</script>

Usage ​

Props ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

The structure below can be used for most cases. If you need a description, see the section on that feature below.

<span class="cdx-checkbox">
  <!-- <input> element with id, type, and any other necessary attributes.
	The actual input is visually hidden. -->
  <input id="checkbox-css-only-1" class="cdx-checkbox__input" type="checkbox" />
  <!-- Empty span that will be styled to look like a checkbox input. -->
  <span class="cdx-checkbox__icon"></span>
  <!-- Label with `for` attribute matching the input's id. -->
  <label class="cdx-checkbox__label" for="checkbox-css-only-1">
    Checkbox 1
  </label>
</span>

With description ​

To add a description below the label:

• Add a span after the <label> element with an ID and class cdx-label__description. Include the description text here.
• Add class cdx-label__label to the <label> element
• Wrap the label and description in a div with classes cdx-checkbox__label and cdx-label
• Add an aria-describedby attribute to the <input> element with the value of the ID of the description

<span class="cdx-checkbox">
  <input
    id="checkbox-description-css-only-1"
    class="cdx-checkbox__input"
    type="checkbox"
    aria-describedby="cdx-description-css-1"
  />
  <span class="cdx-checkbox__icon"></span>
  <div class="cdx-checkbox__label cdx-label">
    <label for="checkbox-description-css-only-1" class="cdx-label__label">
      Send password reset emails only when both email address and username are
      provided.
    </label>
    <span id="cdx-description-css-1" class="cdx-label__description">
      This improves privacy and helps prevent unsolicited emails.
    </span>
  </div>
</span>

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 disabled attribute to the <input> element if it should be disabled.

Note that indeterminate is not supported in the CSS-only version since it cannot be set without JavaScript.

Always include one of these two features for accessible grouping:

1. If using the Checkbox group in a field, wrap the group in a <fieldset> element and add a <legend> element with the group label. This method is demonstrated below and requires some style resets on <fieldset> and <legend>. You can use the CSS-only Field and Label components to reset browser styles of these elements.
2. If using the Checkbox group outside of a field, wrap the group in a <div> with role="group" and aria-labelledby set to the ID of the group label. See an example of this above (you can just include a <label> element instead of using the Label component).

<fieldset class="cdx-field">
  <legend class="cdx-label">
    <span class="cdx-label__label__text">CSS-only Checkbox group demo</span>
  </legend>
  <div class="cdx-field__control">
    <span class="cdx-checkbox">
      <input
        id="checkbox-group-css-only-1"
        class="cdx-checkbox__input"
        type="checkbox"
      />
      <span class="cdx-checkbox__icon"></span>
      <label class="cdx-checkbox__label" for="checkbox-group-css-only-1">
        Checkbox 1
      </label>
    </span>
    <span class="cdx-checkbox">
      <input
        id="checkbox-group-css-only-2"
        class="cdx-checkbox__input"
        type="checkbox"
        checked
      />
      <span class="cdx-checkbox__icon"></span>
      <label class="cdx-checkbox__label" for="checkbox-group-css-only-2">
        Checkbox 2 (initially selected)
      </label>
    </span>
    <span class="cdx-checkbox">
      <input
        id="checkbox-group-css-only-3"
        class="cdx-checkbox__input"
        type="checkbox"
      />
      <span class="cdx-checkbox__icon"></span>
      <label class="cdx-checkbox__label" for="checkbox-group-css-only-3">
        Checkbox 3, which has a very long label that spans onto a second line to
        demonstrate what happens when text wraps
      </label>
    </span>
    <span class="cdx-checkbox">
      <input
        id="checkbox-group-css-only-4"
        class="cdx-checkbox__input"
        type="checkbox"
        disabled
      />
      <span class="cdx-checkbox__icon"></span>
      <label class="cdx-checkbox__label" for="checkbox-group-css-only-4">
        Checkbox 4 (disabled)
      </label>
    </span>
    <span class="cdx-checkbox">
      <input
        id="checkbox-group-css-only-5"
        class="cdx-checkbox__input"
        type="checkbox"
        checked
        disabled
      />
      <span class="cdx-checkbox__icon"></span>
      <label class="cdx-checkbox__label" for="checkbox-group-css-only-5">
        Checkbox 5 (initially selected, disabled)
      </label>
    </span>
  </div>
</fieldset>

Inline checkboxes ​

Add the cdx-checkbox--inline class to the root element to get an inline layout.

<span class="cdx-checkbox cdx-checkbox--inline">
  <input
    id="checkbox-group-inline-css-only-1"
    class="cdx-checkbox__input"
    type="checkbox"
  />
  <span class="cdx-checkbox__icon"></span>
  <label class="cdx-checkbox__label" for="checkbox-group-inline-css-only-1">
    Checkbox 1
  </label>
</span>
<span class="cdx-checkbox cdx-checkbox--inline">
  <input
    id="checkbox-group-inline-css-only-2"
    class="cdx-checkbox__input"
    type="checkbox"
  />
  <span class="cdx-checkbox__icon"></span>
  <label class="cdx-checkbox__label" for="checkbox-group-inline-css-only-2">
    Checkbox 2
  </label>
</span>