Checkbox — Guidelines

When to use

Control	Use for
Checkbox (catnip-checkbox)	A single option: consent line, standalone boolean, or one row with its own error message.
Checklist (catnip-checklist)	Multiple related options with a field label, options + modelValue, and group-level supporting text.
Toggle	A single on/off setting where the metaphor is “enable/disable”.
Radio (future)	Exactly one choice from a small set.

Option row

catnip-checkbox exposes option label text in the default slot (or aria-label when the slot is empty). It does not include a field label or group legend — use catnip-checklist for that.

Optional supporting-text renders below the checkbox row (not inside the clickable label), for per-option hints or validation — matching Figma Checkbox input with an info message.

Indeterminate

Set .indeterminate="true" on the host when a parent represents a partial selection (e.g. some but not all child rows checked). Clear indeterminate when the user selects all or none.

The component synchronizes this visual state to the native checkbox's indeterminate property so assistive technology can expose the mixed state.

Interaction states

• Interactive unchecked boxes are transparent, allowing the surrounding surface to show through.
• Checked and indeterminate boxes use one uninterrupted semantic background colour with component-specific check and dash marks.
• Disabled and read-only styles take precedence over intent="danger", including checked and indeterminate states.
• Danger hover styling applies only to interactive options and uses the dedicated danger hover border/background tokens.
• Disabled and read-only unchecked boxes use the disabled subtler background token.

Read-only checkboxes remain keyboard focusable, expose aria-readonly="true", and reject pointer and keyboard state changes. The current read-only presentation does not apply the component focus ring. Disabled checkboxes use the native disabled state and leave the tab order.

Validation

• Single checkbox: set intent="danger" and supporting-text on the host; the input sets aria-invalid.
• Checkbox groups: put the group label and field-level supporting-text on catnip-checklist. Set intent and supportingText on the matching options row when one option is invalid.

Dropdown lists

Multi-select catnip-dropdown rows use the same checkbox chrome internally — do not render catnip-checkbox inside list options.