Form inputs

Checkbox

<forma-checkbox>

A native checkbox with a delegated touch target, non-color checked cue, and physics-derived CSS state motion.

Authoring tag
<forma-checkbox>
Category
Form inputs
Behavior owner
Native HTML
Canonical source
patterns/checkbox.html

Purpose

A checkbox records an independent yes-or-not-selected choice that usually takes effect when a form is submitted: agreeing to terms, including an option, or selecting items. Forma keeps the native input type="checkbox" as the focusable, form-owning element, stretches it invisibly over the whole row so the label is the touch target, and draws a box with a check mark that appears on :checked.

Use when

  • The user confirms or opts in to one thing, such as consent or "Include archived items".
  • Several independent options can each be on or off, grouped in a fieldset.
  • The choice applies when a form is submitted rather than immediately.

Avoid when

  • The control is a setting that takes effect immediately: use Switch.
  • The user answers a yes/no question that can also be unanswered: use Binary choice.
  • Only one option in a set may be chosen: use Choice group or Segmented control.
  • The options are rich assessment answers with extra context: use Multi-choice, which uses the .forma-choice card presentation.

Behavior to know

  • The whole row, including the label and description, toggles the checkbox.
  • A check mark glyph, not only fill color, shows the checked state.
  • Motion never delays the checked value; the mark animates after the state has changed.

Basic example

The smallest correct markup: the canonical pattern from patterns/checkbox.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal checkbox

Rendered from the canonical pattern file.

HTML · Minimal checkbox Raw HTML for HTML · Minimal checkbox
<forma-checkbox class="forma-component-tag">
<label class="forma-checkbox" data-forma-motion-weight="standard">
  <input
    class="forma-checkbox__input"
    type="checkbox"
    name="audit-log"
    value="enabled"
    aria-describedby="audit-log-description">
  <span class="forma-checkbox__box" aria-hidden="true"></span>
  <span class="forma-checkbox__text">
    <span class="forma-checkbox__label">Record audit events</span>
    <span class="forma-checkbox__description" id="audit-log-description">Include this action in the audit trail.</span>
  </span>
</label>
</forma-checkbox>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Export options

Independent options grouped in a fieldset with a legend. One starts checked, and one is disabled with the reason in its description.

Include in export
HTML · Export options Raw HTML for HTML · Export options
<forma-checkbox class="forma-component-tag">
  <fieldset class="forma-stack" data-density="compact">
    <legend>Include in export</legend>
    <label class="forma-checkbox">
      <input class="forma-checkbox__input" type="checkbox" name="export-include" value="comments" checked>
      <span class="forma-checkbox__box" aria-hidden="true"></span>
      <span class="forma-checkbox__text"><span class="forma-checkbox__label">Comments</span></span>
    </label>
    <label class="forma-checkbox">
      <input class="forma-checkbox__input" type="checkbox" name="export-include" value="attachments">
      <span class="forma-checkbox__box" aria-hidden="true"></span>
      <span class="forma-checkbox__text"><span class="forma-checkbox__label">Attachments</span></span>
    </label>
    <label class="forma-checkbox">
      <input class="forma-checkbox__input" type="checkbox" name="export-include" value="audit" disabled aria-describedby="checkbox-export-audit-description">
      <span class="forma-checkbox__box" aria-hidden="true"></span>
      <span class="forma-checkbox__text">
        <span class="forma-checkbox__label">Audit history</span>
        <span class="forma-checkbox__description" id="checkbox-export-audit-description">Only workspace owners can export audit history.</span>
      </span>
    </label>
  </fieldset>
</forma-checkbox>

Click or tap the code once to select all of it, then copy.

Scenario

Light motion weight with a long label

A light presentation weight gives the check mark a quicker settle. The long translated label wraps beside the box; the box stays aligned to the row.

HTML · Light motion weight with a long label Raw HTML for HTML · Light motion weight with a long label
<forma-checkbox class="forma-component-tag">
  <label class="forma-checkbox" data-forma-motion-weight="light">
    <input class="forma-checkbox__input" type="checkbox" name="notify-subscribers" value="yes">
    <span class="forma-checkbox__box" aria-hidden="true"></span>
    <span class="forma-checkbox__text">
      <span class="forma-checkbox__label">Benachrichtigen Sie alle Abonnenten dieses Projekts per E-Mail, wenn sich der Veröffentlichungsstatus ändert</span>
    </span>
  </label>
</forma-checkbox>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile filter list

Status filters in a narrow panel. Every row is a full-width touch target and labels wrap instead of truncating.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The box column is a fixed 1.25rem; the text column takes the remaining width and wraps long labels.
  • Each row keeps a 44px minimum height and the whole row, not only the box, toggles the checkbox on tap.
  • Nothing scrolls horizontally at 320px.
  • Orientation changes only reflow the text column.
HTML · Mobile filter list Raw HTML for HTML · Mobile filter list
<forma-checkbox class="forma-component-tag">
  <fieldset class="forma-stack" data-density="compact">
    <legend>Status</legend>
    <label class="forma-checkbox">
      <input class="forma-checkbox__input" type="checkbox" name="mobile-status" value="open" checked>
      <span class="forma-checkbox__box" aria-hidden="true"></span>
      <span class="forma-checkbox__text"><span class="forma-checkbox__label">Open</span></span>
    </label>
    <label class="forma-checkbox">
      <input class="forma-checkbox__input" type="checkbox" name="mobile-status" value="waiting">
      <span class="forma-checkbox__box" aria-hidden="true"></span>
      <span class="forma-checkbox__text"><span class="forma-checkbox__label">Waiting on customer response</span></span>
    </label>
    <label class="forma-checkbox">
      <input class="forma-checkbox__input" type="checkbox" name="mobile-status" value="resolved">
      <span class="forma-checkbox__box" aria-hidden="true"></span>
      <span class="forma-checkbox__text"><span class="forma-checkbox__label">Resolved in the last 7 days</span></span>
    </label>
  </fieldset>
</forma-checkbox>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
typeinputcheckbox—Required. The control is a native checkbox.
nameinputstring—Form field name. Checkboxes in a set can share a name to submit several values.
valueinputstring"on"Submitted value when checked.
checkedinputbooleanabsentInitial checked state. The live state is the browser-owned checked property.
requiredinputbooleanabsentThe form will not submit until this checkbox is checked. Say "required" in the label.
disabledinputbooleanabsentRemoves the checkbox from focus and submission and dims the whole row.
aria-describedbyinputid of .forma-checkbox__description—Links the supporting description.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-checkboxBlock class—Root label element: an inline grid of box and text that makes the whole row the hit target, at least 44px tall.
.forma-checkbox__boxElement class—Decorative 1.25rem box; its ::after draws the check mark. Mark it aria-hidden="true".
.forma-checkbox__descriptionElement class—Optional supporting text referenced by aria-describedby.
.forma-checkbox__inputElement class—The native checkbox, transparent and stretched over the row.
.forma-checkbox__labelElement class—Visible accessible name.
.forma-checkbox__textElement class—Label and description column that shrinks and wraps.
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass for the check-mark settle: light, standard (default) or heavy. Never encodes importance or risk.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to and from the checkbox (skipped when disabled).
SpaceToggles the checkbox (native).
Events
EventDescription
input / changeNative events when the user toggles the checkbox. Forma adds none.

Form behavior

A native checkbox: submits name=value only when checked, supports required, restores its initial checked attribute on reset and is excluded when disabled.

States

Checkbox states
StateHow it is expressedPresentation
Uncheckedno checked attributeEmpty box with a functional border.
Checkedchecked / :checkedBox fills with the active control color and a ✓ mark appears, so the state does not rely on color.
Focus:focus-visible on the inputTwo-tone focus ring drawn around the box.
Pressed:active on the inputThe box scales down slightly while pressed; the hit target does not move.
Disableddisabled attributeWhole row at reduced opacity with a not-allowed cursor.

Accessibility

Forma provides

  • The native checkbox stays the focusable, labelled element, so role, state and Space activation come from the platform.
  • The label wraps the input and the input covers the row, giving a large touch target of at least 44px height.
  • The ✓ glyph is a non-color checked cue, and the focus ring is drawn on the visible box.
  • Colors come from semantic tokens that project to system colors in forced-colors mode.

Your application supplies

  • Group related checkboxes in a fieldset with a legend.
  • Say "required" in the label of a required checkbox and explain disabled ones in the description.
  • Indeterminate (mixed) state can only be set from script and has no Forma styling; the application must render and announce it if needed.

Responsive behavior

  • Inline-grid with a fixed box column and a minmax(0, 1fr) text column; long labels wrap and never widen the page.
  • Each row keeps a 44px minimum block size at every width.
  • No breakpoints; stack rows in a fieldset or Stack for full-width lists on phones.

Motion

  • The check mark fades in and settles with the shared inertial spring (scale and a small rotation), so checking reads as a physical mark being placed.
  • The box fill and border change with perceptual interpolation, independent of mass.
  • Pressing compresses the box briefly with a damped press response; the checked value changes immediately and is never delayed by motion.
  • data-forma-motion-weight light, standard or heavy changes only perceived mass of the mark's settle.
  • Under prefers-reduced-motion: reduce durations become effectively zero, press compression is removed, and the mark still appears.

Motion weights

Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:

lightpresentation only
standardpresentation only
heavypresentation only

Usage guidance

Do

  • Write labels as positive statements that are true when checked.
  • Use one checkbox per independent option and a fieldset for sets.

Avoid

  • Using a checkbox for a setting that applies immediately; use a switch.
  • Pre-checking consent or marketing opt-ins.
  • Changing importance or risk through motion weight.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.