Selection and choice

Multi-choice

<forma-multi-choice>

Checkbox-backed selection with explicit guidance for minimum, maximum, or exclusive choices.

Authoring tag
<forma-multi-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

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.

Canonical

Minimal multi-choice

Rendered from the canonical pattern file.

Select exactly two priorities.

Choose exactly 2 options. “None of these” cannot be combined with another option.

0 of 2 selected

HTML · Minimal multi-choice Raw HTML for HTML · Minimal multi-choice
<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

Scenario

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.

Which topics should your weekly digest cover?

Choose up to 3 topics. Clear one to pick a different topic.

3 of 3 selected. Limit reached.

HTML · Maximum reached Raw HTML for HTML · Maximum reached
<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.

Scenario

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.

Which of these tools does your team use?

Choose at least 1. “I don't use any of these” cannot be combined with another option.

1 selected: I don't use any of these.

HTML · Exclusive option chosen Raw HTML for HTML · Exclusive option chosen
<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.

Mobile example

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.

Viewport width

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

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.
HTML · Between-two-and-four rule on a phone Raw HTML for HTML · Between-two-and-four rule on a phone
<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.

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. Each option is a native checkbox; the card draws a square indicator for checkboxes.
nameinputstring—Usually shared by all options so the form submits one name with several values.
valueinputstring"on"Submitted value for each checked option.
checkedinputbooleanabsentInitial selection.
disabledinputbooleanabsentUsed by the application to prevent exceeding a maximum; dims the card.
aria-describedbyfieldsetid of .forma-selection-guidance—Associates the selection rule with the group so it is announced on entry.
aria-live.forma-selection-statuspolite—Announces the application's updated count without interrupting.
data-forma-state.forma-selection-statusincomplete | valid (application vocabulary)—Records the application's cardinality state for tests and integrations. Forma does not style it; the text carries the meaning.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-selection-guidanceBlock class—Secondary-color, small text stating the selection rule; placed after the legend and before the options.
.forma-selection-statusBlock 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.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through each checkbox in turn; every enabled option is its own tab stop.
SpaceToggles the focused checkbox (native behavior).
Events
EventDescription
input / changeNative 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

Multi-choice states
StateHow it is expressedPresentation
Unchecked / checked:checkedChecked cards show a filled square, accent border and secondary surface; forced-colors mode uses Highlight.
Incompletestatus text, e.g. data-forma-state="incomplete"Fewer selections than the rule requires. Expressed only by the status wording.
Rule metstatus text, e.g. data-forma-state="valid"The count satisfies the rule.
Limit reacheddisabled on remaining options plus status textThe application prevents further selection and says so.
Exclusive optionclass forma-choice--exclusive plus visible textDashed card border and an explanatory line. The application clears other options when it is checked.
Focus:focus-visible on a checkboxTwo-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-guidance and link it to the fieldset with aria-describedby.
  • Update forma-selection-status text 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: reduce the 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.