Selection and choice

Hierarchical multi-choice

<forma-hierarchical-multi-choice>

Multi-selection across a hierarchy with application-owned propagation and selection rules.

Authoring tag
<forma-hierarchical-multi-choice>
Behavior owner
Application / Limen
Canonical source
patterns/hierarchical-multi-choice.html

Purpose

Hierarchical multi-choice lets people check several items grouped under collapsible categories. It uses the same forma-hierarchy fieldset, forma-hierarchy__tree nested list and native details/summary branches as Hierarchical choice, with native checkboxes instead of radios, and usually an forma-selection-status line reporting the count. Forma deliberately does not decide what a parent means: whether checking a category includes its children, whether a partly checked branch shows a mixed state (the indeterminate property can only be set by script), and how selections cascade or are validated are application or Limen rules. The native baseline is independent checkboxes that submit exactly what is checked.

Use when

  • Several items can be chosen from a grouped set (affected services, notification categories, permissions by area).
  • Users benefit from collapsing groups they do not need.
  • The application has a clear, stated rule for what selecting a category means, or treats every item independently.

Avoid when

Behavior to know

  • Every item is an independent native checkbox; there is no built-in parent/child propagation.
  • Categories are native disclosures with 44px summary rows and a guide line per branch.
  • Counts and partial selection are communicated in text written by the application, not by color or a mixed-state glyph.

Basic example

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

Canonical

Minimal hierarchical multi-choice

Rendered from the canonical pattern file.

Live demo. 2 native actions work here and are verified by an outcome test.

Choose affected services.

Parent/descendant selection semantics are supplied by the application. The design system does not infer whether selecting a parent includes its children.

  • Platform
  • Data

2 services selected

HTML · Minimal hierarchical multi-choice Raw HTML for HTML · Minimal hierarchical multi-choice
<forma-hierarchical-multi-choice class="forma-component-tag">
<fieldset class="forma-hierarchy">
  <legend class="forma-hierarchy__legend">Choose affected services.</legend>
  <p class="forma-field__description">Parent/descendant selection semantics are supplied by the application. The design system does not infer whether selecting a parent includes its children.</p>

  <ul class="forma-hierarchy__tree">
    <li>
      <details open>
        <summary>Platform</summary>
        <ul>
          <li><label><input type="checkbox" name="services" value="identity"> Identity</label></li>
          <li><label><input type="checkbox" name="services" value="billing"> Billing</label></li>
        </ul>
      </details>
    </li>
    <li>
      <details>
        <summary>Data</summary>
        <ul>
          <li><label><input type="checkbox" name="services" value="warehouse"> Warehouse</label></li>
          <li><label><input type="checkbox" name="services" value="analytics"> Analytics</label></li>
        </ul>
      </details>
    </li>
  </ul>

  <p class="forma-selection-status" data-forma-state="valid" aria-live="polite">2 services selected</p>
</fieldset>
</forma-hierarchical-multi-choice>

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

Examples

Scenario

Category option that includes its children

The application's rule is that "All Platform services" covers current and future Platform services. It is rendered as an explicit option whose description states the rule; the application, not Forma, keeps the child checkboxes consistent with it.

Live demo. 2 native actions work here and are verified by an outcome test.

Send alerts for these services

Choosing an “All” option also covers services added to that area later.

  • Platform
  • Data

All Platform services selected

HTML · Category option that includes its children Raw HTML for HTML · Category option that includes its children
<forma-hierarchical-multi-choice class="forma-component-tag">
  <fieldset class="forma-hierarchy" aria-describedby="hierarchical-multi-choice-category-includes-children-rule">
    <legend class="forma-hierarchy__legend">Send alerts for these services</legend>
    <p class="forma-selection-guidance" id="hierarchical-multi-choice-category-includes-children-rule">Choosing an “All” option also covers services added to that area later.</p>
    <ul class="forma-hierarchy__tree">
      <li>
        <details open>
          <summary>Platform</summary>
          <ul>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-category-includes-children" value="platform-all" checked> All Platform services</label></li>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-category-includes-children" value="identity" checked disabled> Identity (included)</label></li>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-category-includes-children" value="billing" checked disabled> Billing (included)</label></li>
          </ul>
        </details>
      </li>
      <li>
        <details>
          <summary>Data</summary>
          <ul>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-category-includes-children" value="data-all"> All Data services</label></li>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-category-includes-children" value="warehouse"> Warehouse</label></li>
          </ul>
        </details>
      </li>
    </ul>
    <p class="forma-selection-status" data-forma-state="valid" aria-live="polite">All Platform services selected</p>
  </fieldset>
</forma-hierarchical-multi-choice>

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

Scenario

Partial selection stated in the summary

Items are independent. The application writes each branch's count into its summary, so a collapsed branch still tells the user that something inside it is checked. This replaces a mixed-state checkbox, which would need script.

Live demo. 2 native actions work here and are verified by an outcome test.

Which datasets should the export include?
  • Sales (1 of 3 selected)
  • Support (none selected)

1 dataset selected

HTML · Partial selection stated in the summary Raw HTML for HTML · Partial selection stated in the summary
<forma-hierarchical-multi-choice class="forma-component-tag">
  <fieldset class="forma-hierarchy">
    <legend class="forma-hierarchy__legend">Which datasets should the export include?</legend>
    <ul class="forma-hierarchy__tree">
      <li>
        <details>
          <summary>Sales (1 of 3 selected)</summary>
          <ul>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-partial-branch-in-text" value="orders" checked> Orders</label></li>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-partial-branch-in-text" value="refunds"> Refunds</label></li>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-partial-branch-in-text" value="quotes"> Quotes</label></li>
          </ul>
        </details>
      </li>
      <li>
        <details>
          <summary>Support (none selected)</summary>
          <ul>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-partial-branch-in-text" value="tickets"> Tickets</label></li>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-partial-branch-in-text" value="csat"> Satisfaction scores</label></li>
          </ul>
        </details>
      </li>
    </ul>
    <p class="forma-selection-status" data-forma-state="valid" aria-live="polite">1 dataset selected</p>
  </fieldset>
</forma-hierarchical-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

Notification areas on a phone

Two open branches with long item names at phone width, followed by the status line.

Live demo. 2 native actions work here and are verified by an outcome test.

Viewport width

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

What changes at narrow widths

  • At 44rem and below nested indentation shrinks to 0.75rem and branch padding to 0.5rem so item text keeps most of the width.
  • Each checkbox row is at least 44px tall and the whole label row toggles the checkbox.
  • Long names wrap within their row; there is no horizontal scrolling at 320px.
  • The status line follows the tree in source order, so after scrolling to the end the user sees the count next to the last options.
HTML · Notification areas on a phone Raw HTML for HTML · Notification areas on a phone
<forma-hierarchical-multi-choice class="forma-component-tag">
  <fieldset class="forma-hierarchy">
    <legend class="forma-hierarchy__legend">Notify me about</legend>
    <ul class="forma-hierarchy__tree">
      <li>
        <details open>
          <summary>Projects I own</summary>
          <ul>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-mobile-notification-areas" value="owned-comments" checked> New comments on work items assigned to me</label></li>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-mobile-notification-areas" value="owned-status"> Status changes made by other people</label></li>
          </ul>
        </details>
      </li>
      <li>
        <details open>
          <summary>Projects I follow</summary>
          <ul>
            <li><label><input type="checkbox" name="hierarchical-multi-choice-mobile-notification-areas" value="followed-releases" checked> Releases</label></li>
          </ul>
        </details>
      </li>
    </ul>
    <p class="forma-selection-status" data-forma-state="valid" aria-live="polite">2 notification types selected</p>
  </fieldset>
</forma-hierarchical-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.

Live demo. 2 native actions work here and are verified by an outcome test.

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—Each item is an independent native checkbox.
nameinputstring—Usually shared so the form submits one field with several values.
valueinputstring"on"Immutable item identity supplied by the application.
checkedinputbooleanabsentInitial selection. The application sets it for children when its rules say a parent includes them.
disabledinputbooleanabsentUsed by the application for items that are implied by a parent choice or unavailable; disabled items are not submitted.
opendetailsbooleanabsentInitial expanded state of a branch.
aria-describedbyfieldsetid—Links the application's selection rule to the group.
aria-live.forma-selection-statuspolite—Announces the application's updated count.
data-forma-state.forma-selection-statusapplication vocabulary (for example valid, incomplete)—Unstyled marker of the application's selection state; the text carries the meaning.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-hierarchyBlock class—Owned by Hierarchical choice. Fieldset reset plus branch guide lines and 44px summary and label rows.
.forma-hierarchy__legendElement class—The question above the tree.
.forma-hierarchy__treeElement class—Root list with no markers; nested lists are indented.
.forma-selection-statusBlock class—Owned by Multi-choice. Small semi-bold count line after the tree.
.forma-selection-guidanceBlock class—Owned by Multi-choice. States the application's selection rule before the tree.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through summaries and each rendered checkbox in document order. Items in collapsed branches are skipped until opened.
Enter / Space on a summaryExpands or collapses the branch (native).
Space on a checkboxToggles that item only. Any cascade to other items is application behavior.
Events
EventDescription
changeNative event from each checkbox. The application listens to apply propagation rules and update counts.
toggleNative event when a branch opens or closes.

Form behavior

Submits one name=value per checked, enabled checkbox, including those in collapsed branches. Disabled "included" items are not submitted, so the application must interpret the parent value. There is no native minimum or maximum.

States

Hierarchical multi-choice states
StateHow it is expressedPresentation
Branch collapsed / expandeddetails open attributeChildren are hidden or shown in flow. No expand marker is drawn in Chromium or Firefox because the summary is a flex row.
Item checked:checkedShown by the native checkbox.
Partial branch (application)summary or status textForma has no mixed-state styling; write the count into the summary or status.
Implied by parent (application)checked + disabled with explanatory label textOne way to show children covered by a parent choice; the wording must say so.
Focus:focus-visibleShared two-tone focus ring.

Accessibility

Forma provides

  • Keeps native checkboxes and details/summary, so checked and expanded states are programmatic.
  • Provides 44px rows, indentation and guide lines that do not depend on color.
  • Provides text styles for the rule and the count.

Your application supplies

  • State the parent/child rule in visible guidance if parents imply children.
  • Keep collapsed branches informative, for example by writing the selected count into the summary.
  • If you set indeterminate with script, also expose the partial state in text.
  • Update the status line after changes and keep it short.
  • Own all propagation, validation and any tree keyboard model in Limen/application code.

Responsive behavior

  • Same as Hierarchical choice: rows wrap, indentation tightens at 44rem and below, and expanded branches grow the page vertically.
  • The status line stays after the tree in source order at every width.
  • No horizontal overflow at 320px for three levels of nesting with ordinary labels.

Motion

  • No animation: branches open instantly and checkboxes change immediately. Any cascade the application applies is instant too unless it adds its own motion, which must respect reduced motion.

Usage guidance

Do

  • Choose one propagation rule and apply it everywhere in the product.
  • Say what will be submitted when a parent is chosen.

Avoid

  • Silently checking or unchecking items the user cannot see in a collapsed branch.
  • Relying on a mixed-state glyph alone for partial selection.
  • Putting checkboxes inside summary.

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.