Checkbox

Preview

When to use

Use checkboxes when the user needs to select one or more options from a set, and all options should be visible at once. Common scenarios:

• Multi-select forms (preferences, filters, permissions).
• Agreeing to terms and conditions.
• Selecting items in a list for bulk actions.

When not to use

• Don't use checkboxes for mutually exclusive choices — use Radio buttons instead.
• Avoid checkboxes for binary on/off settings that take immediate effect — use a Switch instead.
• Don't use a single checkbox to replace a Toggle or Switch for real-time settings.

Behaviour

Clicking or activating a checkbox toggles it between checked and unchecked. Multiple checkboxes in a group can all be checked simultaneously.

A parent checkbox controlling a group of children uses an indeterminate state when some — but not all — children are checked.

Anatomy

• Checkbox control — the square input element. Shows a checkmark when checked, a dash when indeterminate, and is empty when unchecked.
• Label — the text associated with the checkbox. Clicking the label also toggles the checkbox.
• Description (optional) — secondary text beneath the label for additional context.

Variants

Checkbox — a standalone checkbox with a label, used in standard form lists.

Checkbox list item — a checkbox within a list item container. Includes a label and an optional description below it. The entire row is the tap/click target.

Checkbox card item — a checkbox within a card container. Includes a label and an optional description. The entire card surface is the tap/click target. Use when items benefit from more visual separation and emphasis.

States

• Default (unchecked) — the checkbox is empty and ready to interact.
• Checked — the checkbox shows a checkmark.
• Indeterminate — shows a dash; used on a parent checkbox when a subset of children is checked.
• Hover — the checkbox control highlights when the cursor moves over it.
• Focus — a visible focus ring appears when navigated via keyboard.
• Disabled — the checkbox is non-interactive and visually reduced. Can be unchecked, checked, or indeterminate.
• Error — a validation error state; the checkbox and its label use error styling.

Placement & layout

Group related checkboxes vertically, with consistent spacing between items. Do not place unrelated checkboxes in the same group without a clear visual separator.

In a checkbox group with a group label, the label sits above the list of options. Form validation errors for the group appear below the group.

Checkbox list items and card items span the full width of their container. Standalone checkboxes align their label to the right of the control.

Accessibility

• Each checkbox must have an associated label — either via a visible <label> element or aria-label.
• A group of checkboxes should be wrapped in a <fieldset> with a <legend> that describes the group.
• Keyboard: Tab to move focus to the checkbox, Space to toggle.
• The indeterminate state must be set programmatically (indeterminate property); it cannot be set with HTML alone.
• Error messages for a checkbox group should be associated via aria-describedby.

Related components

• Radio — for single-select from a set of mutually exclusive options.
• Switch — for immediate on/off toggles that don't require form submission.
• Select — for single or multi-select from a dropdown when screen space is limited.