Checkbox

This component allows the user to select multiple options from a list, or a single option.

The guideline content on this page is synced with Figma and can be used as a source of truth. Open in Figma

Anatomy

Checkbox
Label

Unchecked

A component’s state defines its appearance and behaviour.

Example
HTML

development/documentation/docs/checkbox/examples/states-unchecked.html

<div class="d-flex flex-wrap align-items-center" style="gap: 40px;">
	<div>
		<div class="checkbox">
			<input type="checkbox" id="state-unchecked-enabled">
			<label for="state-unchecked-enabled">Enabled</label>
		</div>
	</div>
	<div>
		<div class="checkbox hover">
			<input type="checkbox" id="state-unchecked-hover">
			<label for="state-unchecked-hover">Hover</label>
		</div>
	</div>
	<div>
		<div class="checkbox focus">
			<input type="checkbox" id="state-unchecked-focused">
			<label for="state-unchecked-focused">Focused</label>
		</div>
	</div>
	<div>
		<div class="checkbox">
			<input type="checkbox" id="state-unchecked-disabled" disabled>
			<label for="state-unchecked-disabled">Disabled</label>
		</div>
	</div>
	<div>
		<div class="checkbox has-error">
			<input type="checkbox" id="state-unchecked-error">
			<label for="state-unchecked-error">Error</label>
		</div>
	</div>
</div>

Checked

These are the different states for the checked states.

Example
HTML

development/documentation/docs/checkbox/examples/states-checked.html

<div class="d-flex flex-wrap align-items-center" style="gap: 40px;">
	<div>
		<div class="checkbox">
			<input type="checkbox" id="state-checked-enabled" checked>
			<label for="state-checked-enabled">Enabled</label>
		</div>
	</div>
	<div>
		<div class="checkbox hover">
			<input type="checkbox" id="state-checked-hover" checked>
			<label for="state-checked-hover">Hover</label>
		</div>
	</div>
	<div>
		<div class="checkbox focus">
			<input type="checkbox" id="state-checked-focused" checked>
			<label for="state-checked-focused">Focused</label>
		</div>
	</div>
	<div>
		<div class="checkbox">
			<input type="checkbox" id="state-checked-disabled" disabled checked>
			<label for="state-checked-disabled">Disabled</label>
		</div>
	</div>
	<div>
		<div class="checkbox has-error">
			<input type="checkbox" id="state-checked-error" checked>
			<label for="state-checked-error">Error</label>
		</div>
	</div>
</div>

Mix

These are the different states for the mix states.

Example
HTML

development/documentation/docs/checkbox/examples/states-mix.html

<div class="d-flex flex-wrap align-items-center" style="gap: 40px;">
	<div>
		<div class="checkbox mixed">
			<input type="checkbox" id="state-mix-enabled">
			<label for="state-mix-enabled">Enabled</label>
		</div>
	</div>
	<div>
		<div class="checkbox mixed hover">
			<input type="checkbox" id="state-mix-hover">
			<label for="state-mix-hover">Hover</label>
		</div>
	</div>
	<div>
		<div class="checkbox mixed focus">
			<input type="checkbox" id="state-mix-focused">
			<label for="state-mix-focused">Focused</label>
		</div>
	</div>
	<div>
		<div class="checkbox mixed">
			<input type="checkbox" id="state-mix-disabled" disabled>
			<label for="state-mix-disabled">Disabled</label>
		</div>
	</div>
	<div>
		<div class="checkbox mixed has-error">
			<input type="checkbox" id="state-mix-error">
			<label for="state-mix-error">Error</label>
		</div>
	</div>
</div>

Label

A label is required for all checkboxes. They should be short and represent a value or yes/no decision.

Clickable area

It is crucial for both the label and the checkbox to be clickable to ensure usability and accessibility for all users. By making the label also clickable, you provide a much larger and more forgiving target, which reduces user frustration and the chance of accidental errors.

Accessibility

Keyboard interaction

All components should be reachable via TAB and SHIFT+TAB keys.

Example
HTML

Label

development/documentation/docs/checkbox/examples/keyboard-interaction.html

<div class="checkbox focus">
	<input type="checkbox" id="keyboard-interaction-example" checked>
	<label for="keyboard-interaction-example">Label</label>
</div>

Best practices

Item 1

Item 2

Item 3

development/documentation/docs/checkbox/examples/content-guidelines-do.html

<div class="d-flex flex-column align-items-start">
	<div class="checkbox">
		<input type="checkbox" id="content-do-1">
		<label for="content-do-1">Item 1</label>
	</div>
	<div class="checkbox">
		<input type="checkbox" id="content-do-2">
		<label for="content-do-2">Item 2</label>
	</div>
	<div class="checkbox">
		<input type="checkbox" id="content-do-3">
		<label for="content-do-3">Item 3</label>
	</div>
</div>

Start with capital letters.

Example
HTML

item 1

item 2

item 3

development/documentation/docs/checkbox/examples/content-guidelines-dont.html

<div class="d-flex flex-column align-items-start">
	<div class="checkbox">
		<input type="checkbox" id="content-dont-1">
		<label for="content-dont-1">item 1</label>
	</div>
	<div class="checkbox">
		<input type="checkbox" id="content-dont-2">
		<label for="content-dont-2">item 2</label>
	</div>
	<div class="checkbox">
		<input type="checkbox" id="content-dont-3">
		<label for="content-dont-3">item 3</label>
	</div>
</div>

Don't

Don’t start with small letters.

Specs

Design

Checkboxes

The disabled style will be applied for any of these: add .disabled class to your .checkbox or <fieldset>, or disabled attribute or disabled class on the input.

Example
HTML

Option one is this

Option two - checked

Option three - disabled

Option four - checked and disabled

development/documentation/docs/checkbox/examples/checkboxes.html

<div class="checkbox">
	<input type="checkbox" id="checkbox-example-1">
	<label for="checkbox-example-1">Option one is this</label>
</div>
<br>
<div class="checkbox mb-24">
	<input type="checkbox" id="checkbox-outline-example-4" checked="checked">
	<label for="checkbox-outline-example-4">Option two - checked</label>
</div>
<br>
<div class="checkbox">
	<input class="disabled" type="checkbox" tabindex="-1" aria-disabled="true" id="checkbox-example-2">
	<label for="checkbox-example-2">Option three - disabled</label>
</div>
<br>
<div class="checkbox disabled">
	<input disabled="disabled" type="checkbox" id="checkbox-example-3" checked="checked">
	<label for="checkbox-example-3">Option four - checked and disabled</label>
</div>

Indeterminate / mixed state

The third checkbox state, when it is between checked and unchecked, can be added by adding .mixed class to the wrapper that contains the .checkbox class.

Example
HTML

Indeterminate option with .mixed class

Indeterminate option and disabled

development/documentation/docs/checkbox/examples/mixed-state.html

<div class="checkbox mixed">
	<input type="checkbox" id="mixed-checkbox-example">
	<label for="mixed-checkbox-example" aria-checked="mixed">Indeterminate option with <code>.mixed</code> class</label>
</div>
<br>
<div class="checkbox mixed">
	<input disabled type="checkbox" id="mixed-checkbox-example-2">
	<label for="mixed-checkbox-example-2" aria-checked="mixed">Indeterminate option and disabled</label>
</div>

Indeterminate via JavaScript

Or you can utilise the :indeterminate pseudo class (MDN Web Docs or caniuse) when manually set via JavaScript (there is no available HTML attribute for specifying it).

Example
HTML

Indeterminate/mixed option

development/documentation/docs/checkbox/examples/mixed-state-js.html

<div class="checkbox">
	<input type="checkbox" id="indeterminate-checkbox">
	<label for="indeterminate-checkbox" aria-checked="mixed">Indeterminate/mixed option</label>
</div>
<script>
	let checkbox = document.getElementById('indeterminate-checkbox');
	let checkboxLabel = checkbox.labels[0];
	checkbox.indeterminate = true;
	checkbox.addEventListener('change', () => {
		checkboxLabel.innerText =  checkbox.checked ? 'Checked option' : 'Unchecked option';
		checkboxLabel.ariaChecked = checkbox.checked;
	});
</script>

Secondary/outline style

Deprecated 2.4 — This feature will be removed in 3.0. Use the default checkbox style instead.

For the secondary style of the checkbox just add the .checkbox-outline class to the .checkbox wrapper.

Example
HTML

Option one - unchecked

Option two - mixed

Option three - checked

Option four - unchecked and disabled

Option five - mixed and disabled

Option six - checked and disabled

development/documentation/docs/checkbox/examples/outline.html

<div class="checkbox checkbox-outline">
	<input type="checkbox" id="checkbox-outline-example-1">
	<label for="checkbox-outline-example-1">Option one - unchecked</label>
</div>
<br>
<div class="checkbox checkbox-outline mixed">
	<input type="checkbox" id="checkbox-outline-example-2">
	<label for="checkbox-outline-example-2">Option two - mixed</label>
</div>
<br>
<div class="checkbox checkbox-outline mb-32">
	<input type="checkbox" id="checkbox-outline-example-3" checked="checked">
	<label for="checkbox-outline-example-3">Option three - checked</label>
</div>
<br>
<div class="checkbox checkbox-outline disabled">
	<input disabled="disabled" type="checkbox" id="checkbox-outline-example-4">
	<label for="checkbox-outline-example-4">Option four - unchecked and disabled</label>
</div>
<br>
<div class="checkbox checkbox-outline mixed disabled">
	<input type="checkbox" id="checkbox-outline-example-5" tabindex="-1">
	<label for="checkbox-outline-example-5">Option five - mixed and disabled</label>
</div>
<br>
<div class="checkbox checkbox-outline disabled">
	<input disabled type="checkbox" id="checkbox-outline-example-6" checked="checked">
	<label for="checkbox-outline-example-6">Option six - checked and disabled</label>
</div>

Disabled as readonly

To present a checkbox in a non-interactive state that preserves its current value, apply the disabled attribute to the input. You can optionally use the .disabled class on the wrapper, for example when disabling a group or to reinforce the visual disabled state.

Why not use the `readonly` attribute?

The HTML readonly attribute has no effect on checkboxes. It is only supported on text-based inputs such as <input type="text"> and <textarea>. Browsers silently ignore readonly on checkboxes, meaning users can still change the value despite the attribute being present.

Use the disabled attribute instead to prevent user interaction. If the value must be submitted with the form, consider adding a hidden <input> that carries the value alongside the disabled control.

Example
HTML

Option one - unchecked

Option two - checked

Option three - mixed

development/documentation/docs/checkbox/examples/readonly-checkboxes.html

<div class="checkbox disabled">
    <input type="checkbox" id="checkbox-disabled-readonly-example-1" disabled>
    <label for="checkbox-disabled-readonly-example-1">Option one - unchecked</label>
</div>
<br>
<div class="checkbox disabled">
    <input type="checkbox" id="checkbox-disabled-readonly-example-2" disabled checked>
    <label for="checkbox-disabled-readonly-example-2">Option two - checked</label>
</div>
<br>
<div class="checkbox mixed disabled">
    <input type="checkbox" id="checkbox-disabled-readonly-example-3" disabled>
    <label for="checkbox-disabled-readonly-example-3">Option three - mixed</label>
</div>

Inline checkboxes

Example
HTML

development/documentation/docs/checkbox/examples/inline.html

<form action="">
    <div class="checkbox mr-24">
        <input type="checkbox" id="inlineCheckbox1" value="option1"> <label for="inlineCheckbox1">Inline checkbox 1</label>
    </div>
    <div class="checkbox mr-24">
        <input type="checkbox" id="inlineCheckbox2" value="option2"> <label for="inlineCheckbox2">Inline checkbox 2</label>
    </div>
    <div class="checkbox mr-24">
        <input type="checkbox" id="inlineCheckbox3" value="option3"> <label for="inlineCheckbox3">Inline checkbox 3</label>
    </div>
</form>

Checkboxes in a block/list format

The vertical/list format of checkboxes can be achieved by using the classic <br> tag, a different approach is by using an unordered list element, or flex box helper classes on a wrapper for the items.

In the following example the flexbox helper classes approach is presented, with a flex-direction column and align-items value as flex-start.

Example
HTML

development/documentation/docs/checkbox/examples/block-list.html

<form action="" class="d-flex flex-column align-items-start mb-32">
	<div class="checkbox">
		<input type="checkbox" id="flexCheckbox1" value="option1"> <label for="flexCheckbox1">Inline checkbox 1</label>
	</div>
	<div class="checkbox">
		<input type="checkbox" id="flexCheckbox2" value="option2"> <label for="flexCheckbox2">Inline checkbox 2</label>
	</div>
	<div class="checkbox">
		<input type="checkbox" id="flexCheckbox3" value="option3"> <label for="flexCheckbox3">Inline checkbox 3</label>
	</div>
</form>

Checkbox

Anatomy

Unchecked

Checked

Mix

Label

Clickable area

Accessibility

Keyboard interaction

Best practices

Content guidelines

Specs

Design

Checkboxes

Indeterminate / mixed state

Indeterminate via JavaScript

Secondary/outline style

Disabled as readonly

Why not use the readonly attribute?

Inline checkboxes

Checkboxes in a block/list format

Why not use the `readonly` attribute?