Skip to content

Checkbox

Stable Available in release assets

Present a single native checkbox and its label as an accessible, keyboard-operable choice without replacing browser semantics.

Checkbox primary example

Show code
<div class="thin-choice-row">
  <input class="thin-choice" id="newsletter" type="checkbox" name="newsletter" value="yes">
  <label for="newsletter">Email me product updates</label>
</div>

Each authored example uses the production assets and includes copyable markup.

Standalone checkbox

A labelled thin-choice host keeps native activation and submission semantics.

Show code
<div class="thin-choice-row">
  <input class="thin-choice" id="newsletter" type="checkbox" name="newsletter" value="yes">
  <label for="newsletter">Email me product updates</label>
</div>

Field-composed checkbox

Compose a checkbox inside a field with a persistent hint.

Show code
<div class="thin-field">
  <div class="thin-choice-row">
    <input class="thin-choice" id="terms" type="checkbox" name="terms" value="accepted" required>
    <label for="terms">I accept the terms</label>
  </div>
  <small class="thin-hint">Required before checkout.</small>
</div>

Independent checkbox group

Related independent checkboxes share a fieldset legend.

Show code
<fieldset class="thin-fieldset">
  <legend>Notification channels</legend>
  <div class="thin-choice-row">
    <input class="thin-choice" id="notify-email" type="checkbox" name="notify-email" value="yes">
    <label for="notify-email">Email</label>
  </div>
  <div class="thin-choice-row">
    <input class="thin-choice" id="notify-sms" type="checkbox" name="notify-sms" value="yes">
    <label for="notify-sms">Text message</label>
  </div>
</fieldset>

Anatomy

  • Unregistered thin-choice host
  • Native input[type=checkbox] child
  • Associated label text
  • Optional thin-choice-row for control-label alignment

Variants and sizes

  • Standalone label-wrapped checkbox — shown above
  • Field-composed checkbox with hint or error — shown above
  • Group of independent checkboxes inside a fieldset — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

  • Unchecked
  • Checked
  • Indeterminate (application-set)
  • Focused
  • Disabled
  • Required error
  • Forced colors
  • Long localized label
  • Narrow container

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

Native checkbox semantics own space activation, click activation, focus, validation, and form submission. Indeterminate is an application-visible presentation only and does not submit a value.

Accessibility

Always associate a visible label with the input. Group related independent checkboxes inside a fieldset with a legend. Do not rely on color alone to communicate the checked state; the native indicator and focus outline remain visible.

Contract
NATIVE
Basis
Native checkbox and <fieldset>/<legend> radio controls; no APG widget
Evidence
  • tests/unit/library/choice-controls.test.ts

API

Wrap the native checkbox in unregistered <thin-choice>. Use .thin-choice-row for horizontal control-label alignment. Keep name, value, checked, disabled, and required on the native input.

Behavior tier: native

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

The native checkbox remains keyboard-operable and submits its value without CSS or JavaScript.

Assets and dependencies

  • /components.css

Dependencies: None

Source: packages/ui/src/items/checkbox/style.ts

Stability evidence

  • Native checkbox semantics, indeterminate contract, and no-JavaScript fixture: test:tests/unit/library/choice-controls.test.ts
  • Complete item-specific API, fallback, and difficult-state documentation: test:tests/unit/library/form-controls-stable.test.ts
  • Cross-theme, density, localized, narrow-container, zoom, and forced-colors fixture: review:site/src/pages/quality/index.astro#quality-review

Composition

Derived from the examples and style specs, not authored.

Composes

Used by