Skip to content

Tree View

  • src
  • index.ts
  • lib
  • button.ts
  • input.ts
  • package.json
  • README.md

A WAI-ARIA tree with single selection, roving tabindex, expand/collapse and keyboard navigation.

<script>
import TreeView from "@invisible-ui/svelte/TreeView.svelte";
</script>
PropTypeDefaultDescription
nodes *TreeNode[]—
expandedstring[][]
selectedstring | nullnull
loadingstring[][]Unloaded parent values with an active request.
loadErrorsstring[][]Unloaded parent values whose latest request failed.
disabledbooleanfalse
label *string—Accessible name for the tree.
labelsRecord<string, string> | undefinedundefinedDisplay labels per value (defaults to the value).
onExpandedChange((expanded: string[]) => void) | undefinedundefinedCalled when the expanded set changes.
onSelectedChange((selected: string) => void) | undefinedundefinedCalled when the selection changes.
onLoadChildren((request: TreeLoadRequest) => void) | undefinedundefinedRequests children from the application; the component never fetches.
iconSnippet<[{ node: VisibleNode }]> | undefinedundefinedLeading icon of a row, hidden from assistive tech.
labelContentSnippet<[{ node: VisibleNode }]> | undefinedundefinedA row's label. Defaults to labels[node.value], then the node value.
  • role="tree" with roving tabindex; Up/Down move between visible rows, Left/Right collapse/expand (or move to parent/child), Home/End jump to ends, Enter/Space select. In right-to-left text Left and Right swap, so the arrow that points into the row still expands it. The disclosure arrow mirrors too.
  • Single selection: at most one node is selected (aria-multiselectable is false). Selecting another node replaces it.
  • Typing a character moves focus to the next visible node whose label starts with it; characters typed in quick succession (within half a second) build one query, so “ba” finds “Banana” after “Apple”. Typing moves focus only: it never selects, expands or collapses a node.
  • The disclosure arrow expands and collapses its node with a pointer, also after a failed load.
  • Assistive technology: not tested.
<TreeView label="Files" nodes={[{ value: "src", children: [{ value: "index.ts" }] }]} expanded={["src"]} />

In Elements, assign structured data through properties. Attribute reflection is reserved for scalar values:

<ds-tree-view id="files" label="Files"></ds-tree-view>
<script type="module">
import "@invisible-ui/elements/define";
const tree = document.querySelector("#files");
tree.nodes = [{ value: "src", children: [{ value: "index.ts" }] }];
tree.expanded = ["src"];
tree.addEventListener("selected-change", (event) => {
tree.selected = event.detail.selected;
});
</script>

In React, renderLabel and renderIcon render a row’s label and leading icon from its node:

<TreeView
label="Files"
nodes={[{ value: "src", children: [{ value: "index.ts" }] }]}
expanded={expanded}
onExpandedChange={setExpanded}
selected={selected}
onSelectedChange={setSelected}
renderIcon={(node) => (node.hasChildren ? <FolderIcon /> : <FileIcon />)}
/>

Tree View does not virtualize rows. DOM virtualization can remove the focused treeitem and makes the sibling metadata difficult to keep truthful. For large remote collections, keep search, filtering, and paging in the application and assign only the current result forest to nodes. Use stable value strings; selected and expanded remain controlled when the visible forest changes.

Treat each result or page as the complete tree currently presented to the user. Announce result counts and page changes outside Tree View.

  • production
  • archive

Archive fails once. Expand it again or press Right Arrow to retry.

Set hasChildren: true and omit children for a parent whose children are not available yet. Expanding it calls onLoadChildren with its value and a request id. Elements emits the equivalent load-children event. The component does not fetch or apply the response.

Reflect the request through loading. On success, replace the controlled nodes forest and remove the value from loading. On failure, remove it from loading and add it to loadErrors. Right Arrow retries a failed expanded node. The disclosure arrow keeps expanding and collapsing it; expanding a collapsed failed node requests its children again.

Elements and React announce the loading and failure messages through one visually hidden live region that stays in the page; the row text describes the treeitem without being a live region of its own.

Keep the latest request id per node and ignore older responses. This prevents a slow response from replacing newer data. Separate nodes can remain in loading at the same time.

function onLoadChildren({ value, requestId }) {
latest.set(value, requestId);
loading = [...loading, value];
load(value).then((children) => {
if (latest.get(value) !== requestId) return;
nodes = replaceChildren(nodes, value, children);
loading = loading.filter((entry) => entry !== value);
});
}

The four node forms are distinct:

  • { value: "file" } is a leaf;
  • { value: "folder", children: [...] } is a loaded parent;
  • { value: "remote", hasChildren: true } is an unloaded parent;
  • { value: "empty", children: [] } is a completed load with no children.

Tree View does not virtualize rows. DOM virtualization can remove the focused treeitem and makes sibling metadata difficult to keep truthful. Measure it against representative large trees only after controlled search, paging and asynchronous children have been applied. Virtualization requires a separate accessibility contract and is not enabled automatically.

Themeable via --ds-tree-*.