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-choicecard 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.
Minimal checkbox
Rendered from the canonical pattern file.
<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
Required consent
A required agreement before creating an account. The native required constraint blocks submission while unchecked; the label names what is being agreed to and links the document.
Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-checkbox class="forma-component-tag">
<form class="forma-stack" action="/signup" method="post">
<label class="forma-checkbox">
<input class="forma-checkbox__input" type="checkbox" name="accept-terms" value="yes" required aria-describedby="checkbox-terms-consent-description">
<span class="forma-checkbox__box" aria-hidden="true"></span>
<span class="forma-checkbox__text">
<span class="forma-checkbox__label">I agree to the data processing terms (required)</span>
<span class="forma-checkbox__description" id="checkbox-terms-consent-description">You can read the terms at example.com/dpa before continuing.</span>
</span>
</label>
<button type="submit">Create account</button>
</form>
</forma-checkbox>
Click or tap the code once to select all of it, then copy.
Export options
Independent options grouped in a fieldset with a legend. One starts checked, and one is disabled with the reason in its description.
<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.
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.
<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 filter list
Status filters in a narrow panel. Every row is a full-width touch target and labels wrap instead of truncating.
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.
<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.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
type | input | checkbox | — | Required. The control is a native checkbox. |
name | input | string | — | Form field name. Checkboxes in a set can share a name to submit several values. |
value | input | string | "on" | Submitted value when checked. |
checked | input | boolean | absent | Initial checked state. The live state is the browser-owned checked property. |
required | input | boolean | absent | The form will not submit until this checkbox is checked. Say "required" in the label. |
disabled | input | boolean | absent | Removes the checkbox from focus and submission and dims the whole row. |
aria-describedby | input | id of .forma-checkbox__description | — | Links the supporting description. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-checkbox | Block 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__box | Element class | — | Decorative 1.25rem box; its ::after draws the check mark. Mark it aria-hidden="true". |
.forma-checkbox__description | Element class | — | Optional supporting text referenced by aria-describedby. |
.forma-checkbox__input | Element class | — | The native checkbox, transparent and stretched over the row. |
.forma-checkbox__label | Element class | — | Visible accessible name. |
.forma-checkbox__text | Element 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. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves focus to and from the checkbox (skipped when disabled). |
| Space | Toggles the checkbox (native). |
| Event | Description |
|---|---|
input / change | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Unchecked | no checked attribute | Empty box with a functional border. |
| Checked | checked / :checked | Box fills with the active control color and a ✓ mark appears, so the state does not rely on color. |
| Focus | :focus-visible on the input | Two-tone focus ring drawn around the box. |
| Pressed | :active on the input | The box scales down slightly while pressed; the hit target does not move. |
| Disabled | disabled attribute | Whole 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-weightlight, standard or heavy changes only perceived mass of the mark's settle.- Under
prefers-reduced-motion: reducedurations 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:
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.