TreeView
Hierarchical, expandable tree of nodes with keyboard navigation and selection
Category: display · WCAG 2.2-AA · display, tree, hierarchy, navigation, files
Variants
- single
- multi
States
- default
- expanded
- collapsed
- selected
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. |
ariaLabel | string | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. |
aria-label | string | — | Accessible label for the tree. |
items | { id: string; label: ReactNode; icon?: ReactNode; children?: TreeNode[] }[] | — | The items to render. |
selectionMode | 'single' | 'multi' | single | Whether one or multiple nodes can be selected ('single' | 'multi'). |
selected | string | string[] | — | The controlled selected node id(s). |
defaultSelected | string | string[] | — | The initially selected node id(s) when uncontrolled. |
onSelectChange | (selected: string | string[]) => void | — | Called with the new selection when it changes. |
onValueChange | (selected: string | string[]) => void | — | Called with the new selection. Preferred over `onSelectChange`, which is the catalog’s only value-carrying handler not named onValueChange and is deprecated. |
expanded | string[] | — | The controlled set of expanded node ids. |
defaultExpanded | string[] | — | The initially expanded node ids when uncontrolled. |
onExpandedChange | (expanded: string[]) => void | — | Called with the new expanded set when it changes. |
Design tokens
--cascivo-tree-indent--cascivo-color-border--cascivo-color-bg-subtle--cascivo-color-text--cascivo-color-text-subtle--cascivo-radius-control--cascivo-focus-ring--cascivo-duration-200--cascivo-ease-out
When to use
- Showing nested, parent/child data the user expands and collapses (file trees, org charts, nav)
- Letting the user pick one or several nodes from a hierarchy
- Navigating deep structures where indentation communicates depth
When not to use
- A flat, non-nested list of choices — use List or StructuredList
- A small set of mutually exclusive sections of prose — use Accordion
How to build an accessible TreeView in React →
Examples
Single select
<TreeView defaultExpanded={["src"]} items={[{ id: "src", label: "src", children: [{ id: "index", label: "index.ts" }] }]} />Multi select
<TreeView selectionMode="multi" items={nodes} onSelectChange={(ids) => set(ids)} />Related components
- Accordion — Accordion stacks a few sequential disclosure sections; TreeView models arbitrary-depth hierarchy
- StructuredList — StructuredList is flat tabular rows; TreeView is nested with expand/collapse