Selection and choice

Hierarchical choice

<forma-hierarchical-choice>

Nested native disclosure and radio structure for choosing one item from a hierarchy, without assigning parent-child domain meaning.

Authoring tag
<forma-hierarchical-choice>
Behavior owner
Native baseline / application semantics
Canonical source
patterns/hierarchical-choice.html

Purpose

Hierarchical choice presents options grouped under collapsible categories and lets the user pick exactly one. It is a fieldset (forma-hierarchy) with a legend and a nested list (forma-hierarchy__tree); each category is a native details/summary, and each option is a native radio inside a label, all sharing one name. The browser owns expand/collapse, selection, submission and reset. Forma provides indentation, a guide line per branch and 44px rows. What the hierarchy means is application data: whether a category itself can be chosen, whether branches start open, and how options are identified are decided by the application, and any tree keyboard model (arrow-key tree navigation, typeahead, lazy loading) is Limen behavior.

Use when

  • One item is chosen from a set that is naturally grouped (services by platform, locations by region, categories by department).
  • The full list is long enough that grouping helps, but short enough to render in the page.
  • The hierarchy must work without script and keep native form submission.

Avoid when

Behavior to know

  • One native radio group across the whole tree: only one option can be checked.
  • Categories are native disclosures; the open state is the open attribute.
  • Rows (summaries and option labels) are at least 44px tall.
  • Each branch is marked with an inline-start guide line and indentation, not color.

Basic example

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

Canonical

Minimal hierarchical choice

Rendered from the canonical pattern file.

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

Choose the affected service.

Published hierarchy data is immutable. Limen coordinates expansion/cascading behavior when needed.

  • Platform
  • Data
HTML · Minimal hierarchical choice Raw HTML for HTML · Minimal hierarchical choice
<forma-hierarchical-choice class="forma-component-tag">
<fieldset class="forma-hierarchy">
  <legend class="forma-hierarchy__legend">Choose the affected service.</legend>
  <p class="forma-field__description">Published hierarchy data is immutable. Limen coordinates expansion/cascading behavior when needed.</p>

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

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

Examples

Scenario

Category-level option

The application allows choosing a whole category, so it renders an explicit "Any Data service" option as the first child of the branch. Making the category selectable is expressed as an ordinary option with its own value, never by clicking the summary.

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

Where did the problem occur?
  • Data
  • Platform
HTML · Category-level option Raw HTML for HTML · Category-level option
<forma-hierarchical-choice class="forma-component-tag">
  <fieldset class="forma-hierarchy">
    <legend class="forma-hierarchy__legend">Where did the problem occur?</legend>
    <ul class="forma-hierarchy__tree">
      <li>
        <details open>
          <summary>Data</summary>
          <ul>
            <li><label><input type="radio" name="hierarchical-choice-parent-level-option" value="data-any"> Any Data service</label></li>
            <li><label><input type="radio" name="hierarchical-choice-parent-level-option" value="warehouse"> Warehouse</label></li>
            <li><label><input type="radio" name="hierarchical-choice-parent-level-option" value="analytics"> Analytics</label></li>
          </ul>
        </details>
      </li>
      <li>
        <details>
          <summary>Platform</summary>
          <ul>
            <li><label><input type="radio" name="hierarchical-choice-parent-level-option" value="platform-any"> Any Platform service</label></li>
            <li><label><input type="radio" name="hierarchical-choice-parent-level-option" value="identity"> Identity</label></li>
          </ul>
        </details>
      </li>
    </ul>
  </fieldset>
</forma-hierarchical-choice>

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

Scenario

Restored selection three levels deep

A saved answer is restored. The application opens every branch on the path to the checked option and repeats the selection as text after the tree, so the answer is visible even if the user collapses the branch.

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

Primary office
  • Europe
    • Germany
    • Ireland
  • North America

Selected: Europe › Germany › Berlin

HTML · Restored selection three levels deep Raw HTML for HTML · Restored selection three levels deep
<forma-hierarchical-choice class="forma-component-tag">
  <fieldset class="forma-hierarchy">
    <legend class="forma-hierarchy__legend">Primary office</legend>
    <ul class="forma-hierarchy__tree">
      <li>
        <details open>
          <summary>Europe</summary>
          <ul>
            <li>
              <details open>
                <summary>Germany</summary>
                <ul>
                  <li><label><input type="radio" name="hierarchical-choice-restored-deep-selection" value="berlin" checked> Berlin</label></li>
                  <li><label><input type="radio" name="hierarchical-choice-restored-deep-selection" value="munich"> Munich</label></li>
                </ul>
              </details>
            </li>
            <li>
              <details>
                <summary>Ireland</summary>
                <ul>
                  <li><label><input type="radio" name="hierarchical-choice-restored-deep-selection" value="dublin"> Dublin</label></li>
                </ul>
              </details>
            </li>
          </ul>
        </details>
      </li>
      <li>
        <details>
          <summary>North America</summary>
          <ul>
            <li><label><input type="radio" name="hierarchical-choice-restored-deep-selection" value="toronto"> Toronto</label></li>
            <li><label><input type="radio" name="hierarchical-choice-restored-deep-selection" value="austin"> Austin</label></li>
          </ul>
        </details>
      </li>
    </ul>
    <p class="forma-selection-status" aria-live="polite">Selected: Europe › Germany › Berlin</p>
  </fieldset>
</forma-hierarchical-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

Nested tree on a phone

A two-level hierarchy with long names at phone width. Indentation tightens at narrow widths so deep options keep most of the line for their text.

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 lists indent by 0.75rem and branches by 0.5rem (instead of 1.25rem and 0.75rem), so three levels still fit at 320px.
  • Summaries and option rows stay at least 44px tall; the whole label row is the tap target for its radio.
  • Long category and option names wrap within the row; nothing scrolls horizontally.
  • Expanding a branch pushes the rest of the tree down in flow; there is no overlay or fixed height to clip it.
HTML · Nested tree on a phone Raw HTML for HTML · Nested tree on a phone
<forma-hierarchical-choice class="forma-component-tag">
  <fieldset class="forma-hierarchy">
    <legend class="forma-hierarchy__legend">Which product area is this feedback about?</legend>
    <ul class="forma-hierarchy__tree">
      <li>
        <details open>
          <summary>Reporting and analytics workspace</summary>
          <ul>
            <li><label><input type="radio" name="hierarchical-choice-mobile-nested-tree" value="scheduled"> Scheduled report delivery by email</label></li>
            <li><label><input type="radio" name="hierarchical-choice-mobile-nested-tree" value="builder"> Dashboard builder</label></li>
          </ul>
        </details>
      </li>
      <li>
        <details>
          <summary>Administration</summary>
          <ul>
            <li><label><input type="radio" name="hierarchical-choice-mobile-nested-tree" value="sso"> Single sign-on configuration</label></li>
          </ul>
        </details>
      </li>
    </ul>
  </fieldset>
</forma-hierarchical-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
typeinputradio—Single choice across the whole hierarchy.
nameinputstring—One name for every radio in the tree, so only one can be checked. Unique per question on the page.
valueinputstring"on"The application's immutable option identity, submitted for the chosen option.
checkedinputbooleanabsentInitial or restored selection. Open the branches that contain it.
opendetailsbooleanabsent (collapsed)Initial expanded state of a branch. The browser toggles it afterwards.
aria-live.forma-selection-statuspolite—Optional. Announces an application-written summary of the current selection.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-hierarchyBlock class—The fieldset: border and padding reset. Branch details get an inline-start guide line and padding; summary and label rows are 44px flex rows.
.forma-hierarchy__legendElement class—The question, in bold above the tree.
.forma-hierarchy__treeElement class—Root list with markers removed and no indentation; nested lists indent by 1.25rem (0.75rem at 44rem and below).
Keyboard interaction
KeysResult
Tab / Shift+TabMoves between summaries and into the radio group (to the checked radio, or the first rendered one).
Enter / Space on a summaryExpands or collapses that branch (native details behavior).
Arrow keys in the radio groupMove to and select the previous or next radio of the same name in document order (native radio behavior). This is not tree navigation; radios inside collapsed branches are not rendered and cannot be reached until their branch is opened.
Space on a radioSelects the focused radio when none is selected.
Events
EventDescription
changeNative event from the newly selected radio.
toggleNative event on a details element when a branch opens or closes.

Form behavior

Submits one name=value for the checked radio. required on one radio makes the whole tree required. A checked radio inside a collapsed branch is still submitted.

States

Hierarchical choice states
StateHow it is expressedPresentation
Branch collapseddetails without openOnly the bold summary row is visible. The summary is laid out as a flex row, so no disclosure triangle is drawn in Chromium or Firefox; the platform announces collapsed.
Branch expandeddetails[open]Child options appear below the summary, indented, beside the branch guide line.
Option selected:checked radioShown by the native radio control itself.
Focus:focus-visibleShared two-tone focus ring on the focused summary or radio.

Accessibility

Forma provides

  • Keeps native details/summary and native radios, so expanded state, checked state and group membership are programmatic.
  • Gives summary and option rows a 44px minimum height and makes the whole label row the target.
  • Shows structure with indentation and a guide line, not color.

Your application supplies

  • Open the branches that contain the current selection, and consider repeating the selection as text outside the tree.
  • Decide and explain whether a category can be chosen; express it as an explicit option, never as a clickable summary.
  • Because collapsed summaries have no drawn expand marker, write summaries as category names users expect to open, and keep the first branch open where sensible.
  • Implement any ARIA tree keyboard model, typeahead or lazy loading in Limen/application code.
  • Keep option values stable; do not derive identity from position in the tree.

Responsive behavior

  • Rows wrap long text; the tree never forces horizontal overflow.
  • At 44rem and below nested indentation and branch padding shrink so deep levels keep usable text width.
  • Expanded branches are in flow; the page grows vertically.
  • Very deep hierarchies still lose width per level; beyond three levels consider a stepwise selection instead.

Motion

  • No animation: branches open and close instantly with the native details state, and radio selection is immediate. There is nothing for reduced motion to remove.

Usage guidance

Do

  • Keep categories to two or three levels.
  • Show the selected path in text when the tree is long.

Avoid

  • Putting radios or buttons inside summary.
  • Inferring that selecting a category means all its children; that is a domain rule for the application.
  • Collapsing the branch that contains the current answer on load.

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.