QdsCheckbox

A binary and indeterminate choice control for the Quantum Design System.

Overview

The qds-checkbox component provides an accessible checkbox with support for checked, unchecked, and indeterminate states. It is form-associated and works standalone or inside qds-field.

When to use a checkbox vs a switch: A checkbox implies a pending change that the user must save. A switch implies an immediate change that is applied without a save step. Use qds-checkbox for form inputs, preferences dialogs, and row selection in data tables. Use qds-theme-switch (or a future switch component) for settings that take effect immediately.

Do not use qds-checkbox for mutually exclusive options — use qds-radio-group instead.

Usage

<qds-checkbox label="Accept terms and conditions" required></qds-checkbox>
<qds-checkbox checked label="Enable notifications"></qds-checkbox>
<qds-checkbox indeterminate label="Select all rows"></qds-checkbox>

Label can also be provided as slotted text content:

<qds-checkbox>Accept terms and conditions</qds-checkbox>

API Reference

Attributes

• checked - Boolean. Whether the checkbox is checked. Reflected.
• indeterminate - Boolean. Shows the indeterminate bar. Set by the consumer only; cleared by user interaction.
• value - String. Value submitted when checked. Default "on".
• label - String. Label text. Also settable as slotted text content.
• hint - String. Helper text below the label.
• error-text - String. Error message shown when invalid is true.
• name - String. Form field name.
• size - "sm" | "md" | "lg". Control size. Default "md".
• disabled - Boolean. Disables interaction and dims the control.
• readonly - Boolean. Checked state holds; no pointer or key response; no dimming.
• required - Boolean. Must be checked to be valid (valueMissing while unchecked).
• invalid - Boolean. Author-forced invalid state.

Properties

• checked - Boolean. Synced with the checked attribute.
• indeterminate - Boolean. Synced with the indeterminate attribute.
• value - String.
• label - String.
• hint - String.
• errorText - String.
• name - String.
• size - "sm" | "md" | "lg".
• disabled - Boolean.
• readonly - Boolean.
• required - Boolean.
• invalid - Boolean.
• validity - Read-only. Returns a QdsValidity object.
• checkValidity() - Returns boolean.
• reportValidity() - Returns boolean; also sets the visible error.
• setCustomValidity(message) - Sets a custom error; empty string clears it.

CSS Parts

• container - The outer wrapper.
• row - The clickable row (hit area).
• box - The checkbox square.
• check - The check glyph (inline SVG).
• indeterminate-bar - The indeterminate bar (inline SVG).
• label - The label text.
• hint - The helper text.
• error - The error message.

CSS Custom Properties

• --qds-checkbox-size - Box size. Default 18px (16px at sm, 20px at lg).
• --qds-checkbox-radius - Box corner radius. Default var(--theme-radius-sm, 4px).
• --qds-checkbox-checked-background - Fill and border colour when checked. Default var(--theme-accent-primary).
• --qds-checkbox-border-color - Resting border colour. Default var(--theme-border-secondary).
• --qds-checkbox-gap - Gap between box and label. Default var(--theme-space-2, 8px).

Events

• change - When checked state is committed. Detail: { component, checked, value }.
• input - Same moment as change; native parity. Detail: { component, checked, value }.
• qds-validity-change - When validity transitions. Detail: QdsValidityChangeEventDetail.

Example

<form id="prefs-form">
  <qds-checkbox name="newsletter" label="Subscribe to newsletter" checked></qds-checkbox>
  <qds-checkbox name="terms" label="Accept terms" required hint="You must accept to continue"></qds-checkbox>
  <qds-checkbox name="extras" label="Optional extras" value="extras-pkg"></qds-checkbox>
</form>
<script>
  document.querySelector('#prefs-form').addEventListener('change', (e) => {
    if (e.target.tagName === 'QDS-CHECKBOX') {
      console.log(e.detail.checked, e.detail.value);
    }
  });
</script>