Navigation

Hierarchy tree

<forma-hierarchy-tree>

Uses semantic nesting and native disclosure for parent-child navigation without inventing tree behavior.

Authoring tag
<forma-hierarchy-tree>
Category
Navigation
Behavior owner
Native HTML / application
Canonical source
patterns/hierarchy-tree.html

Purpose

A hierarchy tree lets users browse and navigate a nested structure such as a repository, organisation or document outline. It is deliberately not an ARIA tree widget: it is a labelled nav of nested lists, where each branch is a native details/summary disclosure and each leaf is a link. The browser owns expand and collapse, keyboard access is ordinary Tab order, and the current page is marked with aria-current="page". The application decides which branches start open and supplies the links.

Use when

  • Navigation destinations form a hierarchy of a few levels that users browse.
  • Branches should be collapsible so the tree stays scannable.
  • A simple, robust structure is preferred over a scripted tree with arrow-key behavior.

Avoid when

  • Users select values from a hierarchy in a form: use Hierarchical choice or Hierarchical multi-choice.
  • Only the path to the current item is needed: use Scope trail.
  • The hierarchy is large and needs type-ahead, arrow-key navigation or lazy loading: build an application tree widget on top of Forma styling.
  • There are only a few flat destinations: use Navigation shell.

Behavior to know

  • Semantic nesting (ul inside li) conveys depth; indentation is 1rem per level.
  • Branch summaries and leaf links are at least 44px tall.
  • The current page link is bold in addition to aria-current.
  • Known gap: summaries are rendered as flex rows, which removes the browser's disclosure triangle in Chromium-based browsers, so there is currently no visual open/closed marker. Expanded state is still exposed programmatically by details.

Basic example

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

Canonical

Minimal hierarchy tree

Rendered from the canonical pattern file.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Minimal hierarchy tree Raw HTML for HTML · Minimal hierarchy tree
<forma-hierarchy-tree class="forma-component-tag">
<nav class="forma-hierarchy-tree" aria-label="Repository hierarchy">
  <ul>
    <li><details open><summary>Application</summary><ul>
      <li><details open><summary>Billing</summary><ul>
        <li><a href="#invoices" aria-current="page">Invoices</a></li>
        <li><a href="#customers">Customers</a></li>
      </ul></details></li>
      <li><details><summary>Operations</summary><ul><li><a href="#runs">Runs</a></li></ul></details></li>
    </ul></details></li>
  </ul>
</nav>
</forma-hierarchy-tree>

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

Examples

Scenario

Current page deep in the tree

Only the branches on the path to the current page are open; sibling branches are collapsed so the tree stays short. The application sets open on the ancestors of the current page.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Current page deep in the tree Raw HTML for HTML · Current page deep in the tree
<forma-hierarchy-tree class="forma-component-tag">
  <nav class="forma-hierarchy-tree" aria-label="Documentation sections">
    <ul>
      <li><details><summary>Getting started</summary><ul>
        <li><a href="#tree-collapsed-install">Installation</a></li>
        <li><a href="#tree-collapsed-first">Your first project</a></li>
      </ul></details></li>
      <li><details open><summary>Guides</summary><ul>
        <li><details open><summary>Deployment</summary><ul>
          <li><a href="#tree-collapsed-containers">Containers</a></li>
          <li><a href="#tree-collapsed-rollbacks" aria-current="page">Rollbacks</a></li>
        </ul></details></li>
        <li><details><summary>Monitoring</summary><ul>
          <li><a href="#tree-collapsed-alerts">Alerts</a></li>
        </ul></details></li>
      </ul></details></li>
      <li><a href="#tree-collapsed-changelog">Changelog</a></li>
    </ul>
  </nav>
</forma-hierarchy-tree>

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

Deep tree on a phone

Four levels at phone width. Indentation per level halves below 30rem so deep items keep usable width.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

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

What changes at narrow widths

  • Below 30rem each nested list indents by 0.5rem instead of 1rem, so four levels cost 1.5rem rather than 3rem of width.
  • Summaries and links remain at least 44px tall; the whole summary row toggles its branch on tap.
  • Long names wrap within their row; there is no horizontal scrolling.
  • Depth is still conveyed by list nesting for assistive technology even though the visual indent is smaller.
HTML · Deep tree on a phone Raw HTML for HTML · Deep tree on a phone
<forma-hierarchy-tree class="forma-component-tag">
  <nav class="forma-hierarchy-tree" aria-label="Repository">
    <ul>
      <li><details open><summary>services</summary><ul>
        <li><details open><summary>checkout</summary><ul>
          <li><details open><summary>payment-gateway</summary><ul>
            <li><a href="#tree-mobile-readme" aria-current="page">README</a></li>
            <li><a href="#tree-mobile-config">configuration reference for regional providers</a></li>
          </ul></details></li>
          <li><a href="#tree-mobile-cart">cart</a></li>
        </ul></details></li>
      </ul></details></li>
    </ul>
  </nav>
</forma-hierarchy-tree>

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.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

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
aria-labelnavstring—Names the navigation landmark.
opendetailsbooleanabsent (collapsed)Initial expanded state set by the application, typically on the ancestors of the current page. The browser toggles it afterwards.
aria-currentlinkpageabsentMarks the current page; Forma renders it bold.
hreflinksURL—Destination for each leaf or branch overview.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-hierarchy-treeBlock class—Root nav. Nested lists lose bullets and indent 1rem per level (0.5rem below 30rem); summaries and links become 44px flex rows; [aria-current="page"] is bold.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through visible summaries and links in document order; content inside collapsed branches is skipped.
Enter / Space on a summaryExpands or collapses that branch (native details behavior).
Enter on a linkFollows the link.
Arrow keysNo tree navigation. Forma does not implement role="tree"; arrow keys scroll the page as usual.
Events
EventDescription
toggleNative event from each details element when it opens or closes.

Form behavior

Does not participate in forms.

States

Hierarchy tree states
StateHow it is expressedPresentation
Collapsed branchdetails without openOnly the summary is shown; children are hidden and unfocusable. There is no visual marker distinguishing a collapsed branch from a leaf beyond the missing children and the lack of link styling.
Expanded branchdetails[open]Children listed and indented beneath the summary.
Current pagearia-current="page"Link text is bold.
Focus:focus-visibleFoundation two-tone focus ring on the summary or link.

Accessibility

Forma provides

  • Uses native disclosure and list semantics, so expanded state, depth and item counts come from the platform without an ARIA tree contract.
  • Gives branches and links 44px targets.
  • Marks the current page with weight in addition to aria-current.

Your application supplies

  • Open the branches on the path to the current page.
  • Until Forma restores a visible disclosure marker, make branch labels recognisable as groups (for example plural nouns) so sighted users can tell them from leaf links.
  • Keep summaries as plain text; put branch pages in a child link rather than inside the summary.
  • If you add role="tree" and arrow-key navigation, implement the full ARIA tree pattern in the application.

Responsive behavior

  • Indent is 1rem per level, reduced to 0.5rem below 30rem.
  • Rows are flex containers with a 44px minimum height; text wraps.
  • No horizontal scroll; very deep trees simply become narrower at each level.

Motion

  • No animation: branches open and close instantly with native details.

Usage guidance

Do

  • Keep labels short and unique among siblings.
  • Limit depth to what users can hold in mind, typically three or four levels.

Avoid

  • Adding role="tree" without implementing the keyboard model it promises.
  • Placing links or buttons inside summary elements.

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.