Tree View
- src
- index.ts
- lib
- input.ts
- package.json
- README.md
A WAI-ARIA tree with single selection, roving tabindex, expand/collapse and keyboard navigation.
Import
Section titled “Import”<script> import TreeView from "@invisible-ui/svelte/TreeView.svelte";</script><script setup> import { TreeView } from "@invisible-ui/vue";</script>import { TreeView } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-tree-view></ds-tree-view>| Prop | Type | Default | Description |
|---|---|---|---|
nodes * | TreeNode[] | — | |
expanded | string[] | [] | |
selected | string | null | null | |
loading | string[] | [] | Unloaded parent values with an active request. |
loadErrors | string[] | [] | Unloaded parent values whose latest request failed. |
disabled | boolean | false | |
label * | string | — | Accessible name for the tree. |
labels | Record<string, string> | undefined | undefined | Display labels per value (defaults to the value). |
onExpandedChange | ((expanded: string[]) => void) | undefined | undefined | Called when the expanded set changes. |
onSelectedChange | ((selected: string) => void) | undefined | undefined | Called when the selection changes. |
onLoadChildren | ((request: TreeLoadRequest) => void) | undefined | undefined | Requests children from the application; the component never fetches. |
icon | Snippet<[{ node: VisibleNode }]> | undefined | undefined | Leading icon of a row, hidden from assistive tech. |
labelContent | Snippet<[{ node: VisibleNode }]> | undefined | undefined | A row's label. Defaults to labels[node.value], then the node value. |
| Prop | Type | Default | Description |
|---|---|---|---|
nodes * | TreeNode[] | — | |
expanded | string[] | () => [] | Expanded parent values; bindable with v-model:expanded. |
selected | string | null | null | Selected value; bindable with v-model:selected. |
loading | string[] | () => [] | Unloaded parent values with an active request. |
loadErrors | string[] | () => [] | Unloaded parent values whose latest request failed. |
disabled | boolean | false | |
label * | string | — | Accessible name for the tree (announced by screen readers). |
labels | Record<string, string> | undefined | Optional per-node display labels, keyed by node value. |
onExpandedChange | (expanded: string[]) => void | undefined | Called whenever the expanded set changes. |
onSelectedChange | (selected: string) => void | undefined | Called whenever the selected value changes. |
onLoadChildren | (request: TreeLoadRequest) => void | undefined | Requests children from the application; the component never fetches. |
| Event | Payload |
|---|---|
update:expanded | expanded: string[] |
update:selected | selected: string |
Slots: icon, label.
| Prop | Type | Default | Description |
|---|---|---|---|
nodes * | TreeNode[] | — | |
expanded | string[] | NONE | Initial (uncontrolled) or current (controlled) expanded parents. |
selected | string | null | null | Initial (uncontrolled) or current (controlled) selected node. |
loading | string[] | NONE | Unloaded parent values with an active request. |
loadErrors | string[] | NONE | Unloaded parent values whose latest request failed. |
disabled | boolean | false | |
label * | string | — | Accessible name for the tree (announced by screen readers). |
labels | Record<string, string> | — | Optional per-node display labels, keyed by node value. |
onExpandedChange | (expanded: string[]) => void | — | Called whenever the expanded set changes. |
onSelectedChange | (selected: string) => void | — | Called whenever the selected value changes. |
onLoadChildren | (request: TreeLoadRequest) => void | — | Requests children from the application; the component never fetches. |
renderIcon | (node: VisibleTreeNode) => ReactNode | — | Leading icon of a row, hidden from assistive tech. |
renderLabel | (node: VisibleTreeNode) => ReactNode | — | A row's label. Defaults to labels[node.value], then the node value. |
No props.
Emits: expanded-change with detail.expanded, selected-change with detail.selected, and load-children with detail.value and detail.requestId. Property reflection never emits any of them.
Accessibility
Section titled “Accessibility”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-multiselectableisfalse). 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.
Example
Section titled “Example”<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 />)}/>Large trees
Section titled “Large trees”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.
Asynchronous children
Section titled “Asynchronous children”- 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.
Virtualization
Section titled “Virtualization”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-*.