Multi-choice
<forma-multi-choice>
Checkbox-backed selection with explicit guidance for minimum, maximum, or exclusive choices.
- Authoring tag
<forma-multi-choice>- Category
- Selection and choice
- Behavior owner
- Native HTML
- Canonical source
patterns/multi-choice.html
Purpose
Multi-choice lets people pick several answers from one set. It reuses the Choice group card (forma-choice-group fieldset, forma-choice labels) with native checkboxes, and adds two text parts: forma-selection-guidance states the rule before the options (exactly two, at most three, between one and four, or that one option is exclusive), and forma-selection-status reports the current count in a polite live region. Forma presents the rule and the count as text; it does not count, enforce limits or clear other options when an exclusive option is chosen. Those behaviors belong to the application or Limen.
Use when
- Several answers can apply at once and each benefits from a readable card.
- The number of answers is constrained (exact, minimum, maximum or a range) and users need to see the rule and their progress.
- The set includes a "None of these" or "Not applicable" answer that cannot be combined with others.
Avoid when
- Only one answer is allowed: use Choice group.
- Each item is an independent setting that applies immediately: use Switch or Checkbox.
- Options are nested in categories: use Hierarchical multi-choice.
- Items are ranked or scored rather than selected: use Ranking or Allocation.
Behavior to know
- Native checkboxes: each option is independently checked, submitted and reset by the browser.
- Checked cards show a filled square indicator plus an accent border and surface change.
- The rule is visible text before the options and is linked to the fieldset with aria-describedby.
- The count is visible text in an
aria-live="polite"region that the application updates. - An exclusive option is marked with a dashed border (
forma-choice--exclusive) and a text label, not by position.
Basic example
The smallest correct markup: the canonical pattern from patterns/multi-choice.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal multi-choice
Rendered from the canonical pattern file.
<forma-multi-choice class="forma-component-tag">
<fieldset class="forma-choice-group" aria-describedby="multi-choice-guidance">
<legend class="forma-choice-group__legend">Select exactly two priorities.</legend>
<p class="forma-selection-guidance" id="multi-choice-guidance">Choose exactly 2 options. “None of these” cannot be combined with another option.</p>
<label class="forma-choice">
<input type="checkbox" name="priorities" value="reliability">
<span class="forma-choice__content"><strong>Reliability</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="priorities" value="speed">
<span class="forma-choice__content"><strong>Delivery speed</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="priorities" value="cost">
<span class="forma-choice__content"><strong>Cost efficiency</strong></span>
</label>
<label class="forma-choice forma-choice--exclusive">
<input type="checkbox" name="priorities" value="none">
<span class="forma-choice__content"><strong>None of these</strong><span>Exclusive option</span></span>
</label>
<p class="forma-selection-status" data-forma-state="incomplete" aria-live="polite">0 of 2 selected</p>
</fieldset>
</forma-multi-choice>
Click or tap the code once to select all of it, then copy.
Examples
Maximum reached
An at-most-three rule with three options already checked. The application has updated the status text to say the limit is reached and has disabled the remaining option, so the user cannot exceed it; the guidance tells them how to change their choice.
<forma-multi-choice class="forma-component-tag">
<fieldset class="forma-choice-group" aria-describedby="multi-choice-maximum-reached-guidance">
<legend class="forma-choice-group__legend">Which topics should your weekly digest cover?</legend>
<p class="forma-selection-guidance" id="multi-choice-maximum-reached-guidance">Choose up to 3 topics. Clear one to pick a different topic.</p>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-maximum-reached-topics" value="releases" checked>
<span class="forma-choice__content"><strong>Releases</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-maximum-reached-topics" value="incidents" checked>
<span class="forma-choice__content"><strong>Incidents</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-maximum-reached-topics" value="billing" checked>
<span class="forma-choice__content"><strong>Billing</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-maximum-reached-topics" value="security" disabled>
<span class="forma-choice__content"><strong>Security advisories</strong><span>Limit reached</span></span>
</label>
<p class="forma-selection-status" data-forma-state="valid" aria-live="polite">3 of 3 selected. Limit reached.</p>
</fieldset>
</forma-multi-choice>
Click or tap the code once to select all of it, then copy.
Exclusive option chosen
The user picked "I don't use any of these". The application has cleared the other checkboxes; the dashed exclusive card and its "Exclusive option" text make the rule visible without relying on border style alone.
<forma-multi-choice class="forma-component-tag">
<fieldset class="forma-choice-group" aria-describedby="multi-choice-exclusive-selected-guidance">
<legend class="forma-choice-group__legend">Which of these tools does your team use?</legend>
<p class="forma-selection-guidance" id="multi-choice-exclusive-selected-guidance">Choose at least 1. “I don't use any of these” cannot be combined with another option.</p>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-exclusive-selected-tools" value="tracker">
<span class="forma-choice__content"><strong>Issue tracker</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-exclusive-selected-tools" value="wiki">
<span class="forma-choice__content"><strong>Team wiki</strong></span>
</label>
<label class="forma-choice forma-choice--exclusive">
<input type="checkbox" name="multi-choice-exclusive-selected-tools" value="none" checked>
<span class="forma-choice__content"><strong>I don't use any of these</strong><span>Exclusive option</span></span>
</label>
<p class="forma-selection-status" data-forma-state="valid" aria-live="polite">1 selected: I don't use any of these.</p>
</fieldset>
</forma-multi-choice>
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.
Between-two-and-four rule on a phone
A range rule with one option checked at phone width. The guidance, cards and status all stack and wrap; the status reports that more selections are needed.
What changes at narrow widths
- Guidance, option cards and the status line stack in one column and wrap long text; nothing scrolls horizontally at 320px.
- Each card spans the full width and is at least 3.25rem tall, so checking an option is an easy tap anywhere on the card.
- The status line stays directly after the last option, so it is visible right after the user acts rather than far away at the top.
- No breakpoint changes the layout; the list is already single-column.
<forma-multi-choice class="forma-component-tag">
<fieldset class="forma-choice-group" aria-describedby="multi-choice-mobile-range-rule-guidance">
<legend class="forma-choice-group__legend">Pick the days you can attend on-site training.</legend>
<p class="forma-selection-guidance" id="multi-choice-mobile-range-rule-guidance">Choose between 2 and 4 days.</p>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-mobile-range-rule-days" value="mon" checked>
<span class="forma-choice__content"><strong>Monday</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-mobile-range-rule-days" value="tue">
<span class="forma-choice__content"><strong>Tuesday</strong></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-mobile-range-rule-days" value="wed">
<span class="forma-choice__content"><strong>Wednesday</strong><span>Afternoon session only</span></span>
</label>
<label class="forma-choice">
<input type="checkbox" name="multi-choice-mobile-range-rule-days" value="thu">
<span class="forma-choice__content"><strong>Thursday</strong></span>
</label>
<p class="forma-selection-status" data-forma-state="incomplete" aria-live="polite">1 of at least 2 selected.</p>
</fieldset>
</forma-multi-choice>
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. Each option is a native checkbox; the card draws a square indicator for checkboxes. |
name | input | string | — | Usually shared by all options so the form submits one name with several values. |
value | input | string | "on" | Submitted value for each checked option. |
checked | input | boolean | absent | Initial selection. |
disabled | input | boolean | absent | Used by the application to prevent exceeding a maximum; dims the card. |
aria-describedby | fieldset | id of .forma-selection-guidance | — | Associates the selection rule with the group so it is announced on entry. |
aria-live | .forma-selection-status | polite | — | Announces the application's updated count without interrupting. |
data-forma-state | .forma-selection-status | incomplete | valid (application vocabulary) | — | Records the application's cardinality state for tests and integrations. Forma does not style it; the text carries the meaning. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-selection-guidance | Block class | — | Secondary-color, small text stating the selection rule; placed after the legend and before the options. |
.forma-selection-status | Block class | — | Small, semi-bold status text after the options reporting the current count. It has no color states; the wording must say whether the rule is met. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through each checkbox in turn; every enabled option is its own tab stop. |
| Space | Toggles the focused checkbox (native behavior). |
| Event | Description |
|---|---|
input / change | Native events from each checkbox. The application listens for change to update the status, disable options at a maximum, and clear others when an exclusive option is checked. |
Form behavior
Each checked option submits name=value. Checkboxes have no native minimum or maximum count; the application validates cardinality and reports it. Form reset restores initial checked states but does not update the status text.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Unchecked / checked | :checked | Checked cards show a filled square, accent border and secondary surface; forced-colors mode uses Highlight. |
| Incomplete | status text, e.g. data-forma-state="incomplete" | Fewer selections than the rule requires. Expressed only by the status wording. |
| Rule met | status text, e.g. data-forma-state="valid" | The count satisfies the rule. |
| Limit reached | disabled on remaining options plus status text | The application prevents further selection and says so. |
| Exclusive option | class forma-choice--exclusive plus visible text | Dashed card border and an explanatory line. The application clears other options when it is checked. |
| Focus | :focus-visible on a checkbox | Two-tone focus ring around the card. |
Accessibility
Forma provides
- Keeps each option a native checkbox inside its label, so name, checked state and Space toggling come from the platform.
- Shows checked state with a filled square in addition to border and surface color, and with Highlight in forced-colors mode.
- Provides visible guidance and status text styles so the rule and the count are never color- or icon-only.
Your application supplies
- State the rule in
forma-selection-guidanceand link it to the fieldset with aria-describedby. - Update
forma-selection-statustext after each change; keep it concise so the live announcement is short. - Enforce minimum, maximum and exclusivity in application code and explain any disabled option.
- Label exclusive options in text ("Exclusive option"), not only with the dashed border.
Responsive behavior
- Single-column cards at every width; long option text, guidance and status wrap.
- No breakpoints; the status stays after the options in source order.
- Large option sets remain one scrolling list; do not switch to horizontal layouts on phones.
Motion
- Card background, border and text color change by perceptual interpolation (about 120ms); nothing moves. Checked state is applied immediately.
- The guidance and status text do not animate. Under
prefers-reduced-motion: reducethe color transition is effectively instant.
Usage guidance
Do
- Write the rule as a number ("Choose up to 3") rather than an adjective ("a few").
- Keep the status next to the options and update it on every change.
Avoid
- Silently unchecking options when an exclusive answer is chosen without the guidance saying so.
- Blocking the user with a disabled submit button instead of explaining the rule.
- Using a switch list when the answers are part of one question.
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.