Checkbox

Material Design 3 checkbox for binary selection with checked, unchecked, and indeterminate states. Not intended for mutually exclusive single-choice scenarios; use radio buttons instead.

Basic Usage

Use checkboxes for independent boolean choices. This is the recommended baseline because each checkbox operates independently and supports three states: checked, unchecked, and indeterminate. 

<ds-checkbox label="Subscribe to newsletter"></ds-checkbox>

Variants

Use the label to describe the choice and optional value.

Default (Unchecked)

Default unselected state.

  • Use when: The user should opt in with no default commitment.
  • Avoid when: One of multiple exclusive options must be selected; use a radio group. 
<ds-checkbox label="Receive product updates"></ds-checkbox>

Checked

Selected state for active choices.

  • Use when: Pre-selecting items that are on by default.
  • Avoid when: Pre-selection might obscure the user's actual preference. 
<ds-checkbox label="Remember me" checked></ds-checkbox>

Sizes

Use size to align with layout density.

<ds-checkbox label="Small" size="sm"></ds-checkbox>
<ds-checkbox label="Medium" size="md"></ds-checkbox>
<ds-checkbox label="Large" size="lg"></ds-checkbox>

States

Show indeterminate, error, and disabled states clearly.

Indeterminate

Use for partial selection (such as select-all lists).

<ds-checkbox label="Select all" indeterminate></ds-checkbox>

Error

Highlight validation issues.

<ds-checkbox label="I agree to the terms" error></ds-checkbox>

Disabled

Disable inputs that cannot be changed.

<ds-checkbox label="Disabled checked" checked disabled></ds-checkbox>

With Labels

Labels provide accessible names for screen readers.

<ds-checkbox label="Email notifications"></ds-checkbox>

API

Attributes

Attribute Type Default Description
label string "" Label text displayed next to the checkbox.
name string "" Form field name.
value string "" Form value when checked.
checked boolean false Checked state.
indeterminate boolean false Indeterminate state.
disabled boolean false Disables the checkbox.
error boolean false Shows error state.
required boolean false Makes the checkbox required.
size string "" Size of the checkbox (sm, md, lg).

Forms

Submits its value (default "on") when checked and nothing when unchecked, like a native checkbox. required means it must be checked. It resets with its form, and a disabled <fieldset> disables it. form, validity, validationMessage, checkValidity() and reportValidity() behave as on a native control.

Events

Event Detail Description
ds-checkbox:change { checked: boolean, indeterminate: boolean, value: string } Fired when the checkbox state changes.

CSS Parts

Part Description
container The checkbox container.
input The hidden native input.
icon The checkbox icon.
label The label text element.
state-layer The interaction state layer.

CSS Custom Properties

Property Description
--ds-checkbox-size Checkbox size (default: var(--ds-size-icon-md, 18px)).
--ds-checkbox-icon-size Checkbox icon size (default: var(--ds-size-icon-md, 18px)).
--ds-checkbox-state-layer-size State layer size (default: var(--ds-size-hit-area, 40px)).

Accessibility

Keyboard Map

Key Context Expected Result
Tab Checkbox not focused Moves focus to the checkbox.
Space Checkbox focused Toggles checked/unchecked state.

Semantics

  • Exposes role="checkbox" and aria-checked.
  • Uses aria-disabled and aria-required when set.
  • Focus indicators meet WCAG 2.2 requirements.

Usage Guidelines

  • When to use: Multiple independent options that can each be on or off, such as feature toggles or multi-select lists.
  • When not to use: Single exclusive choice from a set; use radio buttons. Binary on/off settings; consider a switch.
  • Composition: Group checkboxes with a parent checkbox to support indeterminate state for bulk selection.
  • Common mistakes: Using checkboxes where only one option should be active, and omitting labels.