Skip to content

Tree

Nested items a person opens and closes, chooses, and moves, after the WAI-ARIA tree pattern.

<p>Paluxy Portal, as Carrel's binder would show it. Arrow keys move, Right and Left open and close, Enter opens a file, Alt with an arrow moves a row, and a row drags to a new place. Each move is said in words and reported to the page.</p>
<div class="tree-sample">
  <ul class="cap-tree" data-cap="tree" data-movable data-variant="surface" aria-label="Paluxy Portal binder" id="binder">
    <li class="cap-tree-item" data-value="book"><a class="cap-tree-row" href="#book"><span class="cap-tree-label">Paluxy Portal</span><span class="cap-tree-meta">18,420 words</span></a></li>
    <li class="cap-tree-item" data-value="ch-01">
      <a class="cap-tree-row" href="#ch-01"><span class="cap-tree-label">01 The riverbed</span><span class="cap-tree-meta">6,210</span></a>
      <ul class="cap-tree-group">
        <li class="cap-tree-item" data-value="ch-01/01"><a class="cap-tree-row" href="#ch-01-01" aria-current="page"><span class="cap-tree-label">01 Low water</span><span class="cap-tree-meta"><span class="cap-status" data-tone="ok"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1a7 7 0 1 0 0 14A7 7 0 1 0 8 1zM3.9 9l3 3 5.2-5.6-1.4-1.4-3.8 4.2-1.6-1.6z"/></svg>Revised</span>2,140</span></a></li>
        <li class="cap-tree-item" data-value="ch-01/02"><a class="cap-tree-row" href="#ch-01-02"><span class="cap-tree-label">02 Tracks in the limestone</span><span class="cap-tree-meta"><span class="cap-status" data-tone="info"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="8" cy="8" r="6.2" fill="none" stroke="currentColor" stroke-width="1.6" opacity="0.35"/><path fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" d="M8 1.8a6.2 6.2 0 0 1 6.2 6.2"/></svg>Drafting</span>2,610</span></a></li>
        <li class="cap-tree-item" data-value="ch-01/03"><a class="cap-tree-row" href="#ch-01-03"><span class="cap-tree-label">03 The ranger's notebook</span><span class="cap-tree-meta">1,460</span></a></li>
      </ul>
    </li>
    <li class="cap-tree-item" data-value="ch-02">
      <a class="cap-tree-row" href="#ch-02"><span class="cap-tree-label">02 Flood stage</span><span class="cap-tree-meta">4,980</span></a>
      <ul class="cap-tree-group">
        <li class="cap-tree-item" data-value="ch-02/01"><a class="cap-tree-row" href="#ch-02-01"><span class="cap-tree-label">01 Rain at Glen Rose</span><span class="cap-tree-meta">2,300</span></a></li>
        <li class="cap-tree-item" data-value="ch-02/02"><a class="cap-tree-row" href="#ch-02-02"><span class="cap-tree-label">02 The second set</span><span class="cap-tree-meta">2,680</span></a></li>
      </ul>
    </li>
    <li class="cap-tree-item" data-value="ch-03" data-branch><a class="cap-tree-row" href="#ch-03"><span class="cap-tree-label">03 Untitled chapter</span><span class="cap-tree-meta">empty</span></a></li>
    <li class="cap-tree-item" data-value="bible" data-collapsed>
      <span class="cap-tree-row"><span class="cap-tree-label">Bible</span></span>
      <ul class="cap-tree-group">
        <li class="cap-tree-item" data-value="bible/characters" data-collapsed>
          <span class="cap-tree-row"><span class="cap-tree-label">Characters</span><span class="cap-tree-meta">2</span></span>
          <ul class="cap-tree-group">
            <li class="cap-tree-item" data-value="bible/characters/ines"><a class="cap-tree-row" href="#ines"><span class="cap-tree-label">Ines Calder</span></a></li>
            <li class="cap-tree-item" data-value="bible/characters/wade"><a class="cap-tree-row" href="#wade"><span class="cap-tree-label">Wade Pruitt</span></a></li>
          </ul>
        </li>
        <li class="cap-tree-item" data-value="bible/places" data-collapsed>
          <span class="cap-tree-row"><span class="cap-tree-label">Places</span><span class="cap-tree-meta">1</span></span>
          <ul class="cap-tree-group">
            <li class="cap-tree-item" data-value="bible/places/paluxy"><a class="cap-tree-row" href="#paluxy"><span class="cap-tree-label">The Paluxy crossing</span></a></li>
          </ul>
        </li>
      </ul>
    </li>
    <li class="cap-tree-item" data-value="notes"><a class="cap-tree-row" href="#notes"><span class="cap-tree-label">Notes</span></a></li>
  </ul>
  <output class="tree-sample-out" id="binder-out" for="binder">Nothing moved yet.</output>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/tree.css";
import { enhance } from "capsomer/behavior/tree";

enhance();

Usage

<ul class="cap-tree" data-cap="tree" data-movable aria-label="Paluxy Portal binder">
  <li class="cap-tree-item" data-value="ch-01">
    <a class="cap-tree-row" href="/book/ch-01"><span class="cap-tree-label">01 The riverbed</span><span class="cap-tree-meta">6,210</span></a>
    <ul class="cap-tree-group">
      <li class="cap-tree-item" data-value="ch-01/01"><a class="cap-tree-row" href="/book/ch-01/01" aria-current="page"><span class="cap-tree-label">01 Low water</span></a></li>
    </ul>
  </li>
  <li class="cap-tree-item" data-value="ch-03" data-branch><span class="cap-tree-row"><span class="cap-tree-label">03 Untitled chapter</span></span></li>
  <li class="cap-tree-item" data-value="bible" data-collapsed>...</li>
</ul>
<li class="cap-tree-item" data-value="ch-01" role="none">
  <a class="cap-tree-row" href="/book/ch-01" role="treeitem" aria-level="1" aria-posinset="2" aria-setsize="3" aria-expanded="true" aria-owns="ch-01-group" tabindex="-1"><span class="cap-tree-toggle" aria-hidden="true">...</span><span class="cap-tree-label">01 The riverbed</span></a>
  <ul class="cap-tree-group" role="group" id="ch-01-group">...</ul>
</li>
import { enhance, treeFor, applyMove, reverseMove } from "capsomer/behavior/tree";
enhance(); // every [data-cap="tree"]
el.addEventListener("cap:tree-select", (e) => e.detail); // { id, label, selected, values }
el.addEventListener("cap:tree-toggle", (e) => e.detail); // { id, expanded }
el.addEventListener("cap:tree-move", (e) => save(e.detail)); // { id, from, to }; preventDefault refuses it
treeFor(el).move(reverseMove(last)); // Undo

Examples

As delivered with no script

<p>The same contract before <code>enhance</code> runs: nested lists, every level shown, every link a link. No roles a reader would expect keys for.</p>
<div class="tree-sample">
  <nav aria-label="Binder, no script">
    <ul class="cap-tree" data-variant="surface">
      <li class="cap-tree-item" data-value="ch-01">
        <a class="cap-tree-row" href="#ch-01"><span class="cap-tree-label">01 The riverbed</span><span class="cap-tree-meta">6,210</span></a>
        <ul class="cap-tree-group">
          <li class="cap-tree-item" data-value="ch-01/01"><a class="cap-tree-row" href="#ch-01-01" aria-current="page"><span class="cap-tree-label">01 Low water</span><span class="cap-tree-meta">2,140</span></a></li>
          <li class="cap-tree-item" data-value="ch-01/02"><a class="cap-tree-row" href="#ch-01-02"><span class="cap-tree-label">02 Tracks in the limestone</span><span class="cap-tree-meta">2,610</span></a></li>
        </ul>
      </li>
      <li class="cap-tree-item" data-value="notes"><a class="cap-tree-row" href="#notes"><span class="cap-tree-label">Notes</span></a></li>
    </ul>
  </nav>
</div>

Several chosen, no links, one row not available

<p>Space chooses or clears a row; the page hears each choice. The published chapter cannot be chosen for export again.</p>
<div class="tree-sample">
  <ul class="cap-tree" data-cap="tree" data-selection="multi" data-variant="surface" aria-label="Sections to export" id="export">
    <li class="cap-tree-item" data-value="front">
      <span class="cap-tree-row"><span class="cap-tree-label">Front matter</span></span>
      <ul class="cap-tree-group">
        <li class="cap-tree-item" data-value="front/title"><span class="cap-tree-row" data-selected><span class="cap-tree-label">Title page</span></span></li>
        <li class="cap-tree-item" data-value="front/dedication"><span class="cap-tree-row"><span class="cap-tree-label">Dedication</span></span></li>
      </ul>
    </li>
    <li class="cap-tree-item" data-value="body">
      <span class="cap-tree-row" data-selected><span class="cap-tree-label">Chapters</span></span>
      <ul class="cap-tree-group">
        <li class="cap-tree-item" data-value="body/01"><span class="cap-tree-row" aria-disabled="true"><span class="cap-tree-label">01 The riverbed</span><span class="cap-tree-meta">published</span></span></li>
        <li class="cap-tree-item" data-value="body/02"><span class="cap-tree-row"><span class="cap-tree-label">02 Flood stage</span></span></li>
      </ul>
    </li>
  </ul>
  <output class="tree-sample-out" id="export-out" for="export">Chosen: title page, chapters.</output>
</div>

Row states: under the pointer, keyboard focus, dragged, and where a drop lands

<p>Set from the page, not from a pointer: a row under the pointer, the focus ring, the row being dragged, and the three drop marks, a line before, a ring inside a branch, a line after.</p>
<div class="tree-sample">
  <ul class="cap-tree" data-variant="surface" role="tree" aria-label="Row states">
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-selected="false" tabindex="-1" id="st-hover"><span class="cap-tree-label">Under the pointer</span></span></li>
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-selected="false" tabindex="0" id="st-focus"><span class="cap-tree-label">Keyboard focus</span></span></li>
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-selected="true" tabindex="-1" id="st-chosen"><span class="cap-tree-label">Chosen</span><span class="cap-tree-meta">1,460</span></span></li>
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-selected="false" data-dragging tabindex="-1" id="st-drag"><span class="cap-tree-label">Being dragged</span></span></li>
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-selected="false" data-drop="before" tabindex="-1" id="st-before"><span class="cap-tree-label">A drop before this row</span></span></li>
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-selected="false" aria-expanded="false" data-drop="inside" tabindex="-1" id="st-inside"><span class="cap-tree-toggle" aria-hidden="true"><svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6"/></svg></span><span class="cap-tree-label">A drop inside this branch</span></span></li>
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-selected="false" data-drop="after" tabindex="-1" id="st-after"><span class="cap-tree-label">A drop after this row</span></span></li>
    <li class="cap-tree-item" role="none"><span class="cap-tree-row" role="treeitem" aria-level="1" aria-disabled="true" tabindex="-1" id="st-disabled"><span class="cap-tree-label">Not available</span><span class="cap-tree-meta">published</span></span></li>
  </ul>
</div>

In React: a series of posts, moved and saved by the page

<p>The React wrapper holds which branches are open; the page holds the nodes and saves each move (here, it writes the new order below).</p>
<div data-mount="react"></div>

API reference

Tree

PropTypeRequiredDoes
nodesTreeNode[]Yes
aria-labelstring
aria-labelledbystring
selectionTreeSelection
selectedstring[]
defaultSelectedstring[]
onSelectedChange(ids: string[], node: TreeNode) => void
expandedstring[]
defaultExpandedstring[]
onExpandedChange(ids: string[]) => void
onMove(move: TreeMove, next: TreeNode[]) => voidTurns on moving, by Alt with an arrow and by dragging a row. The caller saves the move.
canMove(move: TreeMove) => booleanRefuses a move before it is offered (a scene may not sit at the top level, say).
variant"surface"Draws its own border and surface, for a tree on its own.
classNamestring

Functions

FunctionSignatureDoes
createTree(el: HTMLElement): Tree
treeFor(el: Element | null): Tree | undefinedThe controller enhance made for this element, if any.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="tree"] under root not yet marked data-cap-ready. Reads data-selection ("none", "single" by default, "multi") and data-movable. Returns a function that detaches them all.

CSS variables

VariableDefault
--tree-depth0
--tree-indentcalc(var(--space-5) + var(--space-1))

Parts and data attributes

ClassIs
.cap-treethe root
.cap-tree-groupa part
.cap-tree-icona part
.cap-tree-labela part
.cap-tree-metaa part
.cap-tree-rowa part
.cap-tree-togglea part
AttributeValues
data-draggingpresent or absent
data-dropafter before inside
data-movablepresent or absent
data-sortingpresent or absent
data-variantsurface
StateRead from
:focus-visiblethe platform
:hoverthe platform
[aria-current="page"]an attribute
[aria-disabled="true"]an attribute
[aria-expanded="true"]an attribute
[aria-selected="true"]an attribute
[hidden]an attribute

Accessibility

KeyDoes
Down arrow, Up arrowNext, previous visible row
Right arrowOpens a closed branch; on an open one, goes to its first child
Left arrowCloses an open branch; otherwise goes to the parent
Home, EndFirst, last visible row
*Opens every branch beside the current one
A letterGoes to the next row starting with the letters typed
EnterOpens a link row (the browser follows it); chooses any other row
SpaceChooses the row; with several, adds or removes it
Alt + Up arrow, Alt + Down arrowMoves the row before or after its neighbor (data-movable)
Alt + Right arrowMoves the row into the branch just above it, at the end
Alt + Left arrowMoves the row out of its branch, to just after it
  • role="tree" named by aria-label or aria-labelledby; each row role="treeitem" with aria-level, aria-posinset and aria-setsize; a branch aria-expanded and aria-owns naming its role="group"; the list items role="none". aria-selected on every row that can be chosen; aria-multiselectable with data-selection="multi"; aria-disabled="true" on one that cannot.
  • The chevron is decoration (aria-hidden); the state is aria-expanded. The note at the end is part of the row's name ("Low water, Revised, 2,140").
  • A move, a refused move ("Low water is already first here.") and a canceled drag are said in a role="status" region that exists before it changes.
  • Dragging is never the only way: every drag has a keyboard move. A host whose people move rows by touch adds a one-pointer command (a "Move to" menu) that calls the same move, as WCAG 2.5.7 asks.