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.
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.
<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
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.
<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.
Branches that are also destinations
When a branch has its own page, the summary stays a plain toggle and the branch page is the first child link. Putting a link inside the summary would create a nested interactive control.
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.
<forma-hierarchy-tree class="forma-component-tag">
<nav class="forma-hierarchy-tree" aria-label="Organisation">
<ul>
<li><details open><summary>Engineering</summary><ul>
<li><a href="#tree-overview-engineering" aria-current="page">Engineering overview</a></li>
<li><details><summary>Platform</summary><ul>
<li><a href="#tree-overview-platform">Platform overview</a></li>
<li><a href="#tree-overview-sre">Site reliability</a></li>
</ul></details></li>
<li><a href="#tree-overview-security">Security</a></li>
</ul></details></li>
<li><details><summary>Operations</summary><ul>
<li><a href="#tree-overview-operations">Operations overview</a></li>
</ul></details></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.
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.
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.
<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.
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.
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 |
|---|---|---|---|---|
aria-label | nav | string | — | Names the navigation landmark. |
open | details | boolean | absent (collapsed) | Initial expanded state set by the application, typically on the ancestors of the current page. The browser toggles it afterwards. |
aria-current | link | page | absent | Marks the current page; Forma renders it bold. |
href | links | URL | — | Destination for each leaf or branch overview. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-hierarchy-tree | Block 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. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through visible summaries and links in document order; content inside collapsed branches is skipped. |
| Enter / Space on a summary | Expands or collapses that branch (native details behavior). |
| Enter on a link | Follows the link. |
| Arrow keys | No tree navigation. Forma does not implement role="tree"; arrow keys scroll the page as usual. |
| Event | Description |
|---|---|
toggle | Native event from each details element when it opens or closes. |
Form behavior
Does not participate in forms.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Collapsed branch | details without open | Only 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 branch | details[open] | Children listed and indented beneath the summary. |
| Current page | aria-current="page" | Link text is bold. |
| Focus | :focus-visible | Foundation 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.