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>- Category
- Selection and 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
- Only one item may be chosen: use Hierarchical choice.
- The set is flat: use Multi-choice.
- Selections need drag, ranking or weights: use Ranking or Allocation.
- The hierarchy is navigation: use Hierarchy tree.
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.
Minimal hierarchical multi-choice
Rendered from the canonical pattern file.
Live demo. 2 native actions work here and are verified by an outcome test.
<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
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.
<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.
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.
<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.
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.
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.
<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.
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.
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 | — | Each item is an independent native checkbox. |
name | input | string | — | Usually shared so the form submits one field with several values. |
value | input | string | "on" | Immutable item identity supplied by the application. |
checked | input | boolean | absent | Initial selection. The application sets it for children when its rules say a parent includes them. |
disabled | input | boolean | absent | Used by the application for items that are implied by a parent choice or unavailable; disabled items are not submitted. |
open | details | boolean | absent | Initial expanded state of a branch. |
aria-describedby | fieldset | id | — | Links the application's selection rule to the group. |
aria-live | .forma-selection-status | polite | — | Announces the application's updated count. |
data-forma-state | .forma-selection-status | application vocabulary (for example valid, incomplete) | — | Unstyled marker of the application's selection state; the text carries the meaning. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-hierarchy | Block class | — | Owned by Hierarchical choice. Fieldset reset plus branch guide lines and 44px summary and label rows. |
.forma-hierarchy__legend | Element class | — | The question above the tree. |
.forma-hierarchy__tree | Element class | — | Root list with no markers; nested lists are indented. |
.forma-selection-status | Block class | — | Owned by Multi-choice. Small semi-bold count line after the tree. |
.forma-selection-guidance | Block class | — | Owned by Multi-choice. States the application's selection rule before the tree. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through summaries and each rendered checkbox in document order. Items in collapsed branches are skipped until opened. |
| Enter / Space on a summary | Expands or collapses the branch (native). |
| Space on a checkbox | Toggles that item only. Any cascade to other items is application behavior. |
| Event | Description |
|---|---|
change | Native event from each checkbox. The application listens to apply propagation rules and update counts. |
toggle | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Branch collapsed / expanded | details open attribute | Children are hidden or shown in flow. No expand marker is drawn in Chromium or Firefox because the summary is a flex row. |
| Item checked | :checked | Shown by the native checkbox. |
| Partial branch (application) | summary or status text | Forma has no mixed-state styling; write the count into the summary or status. |
| Implied by parent (application) | checked + disabled with explanatory label text | One way to show children covered by a parent choice; the wording must say so. |
| Focus | :focus-visible | Shared 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
indeterminatewith 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.