TreeView

Application tree with hierarchical selection, expansion, roving focus, and arrow-key navigation.

Status: beta. Group: navigation. Markdown version: /design-system/components/tree-view.md

When to use

Use TreeView for application hierarchies that users expand, collapse, navigate, and select. Use stable identifiers and concise node labels.

When not to use

Do not replace a sitemap or ordinary nested navigation list.
Do not nest independently focusable controls inside node labels.
Do not use TreeView for a flat set of links or ordinary site navigation.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

TreeView props
Prop	Type	Default	Description	Required
`nodes`	`TreeViewNode[]`	none	Hierarchical nodes.	Yes
`aria-label`	`string`	none	Accessible name for the tree.	Yes
`selectedId`	`string \| null`	none	Controlled selected node identifier.	No
`defaultSelectedId`	`string \| null`	`null`	Initial uncontrolled selected node identifier.	No
`onSelectedIdChange`	`(id: string) => void`	none	Receives selection changes.	No
`expandedIds`	`string[]`	none	Controlled expanded node identifiers.	No
`defaultExpandedIds`	`string[]`	`[]`	Initial uncontrolled expanded node identifiers.	No
`onExpandedIdsChange`	`(ids: string[]) => void`	none	Receives expansion changes.	No
`size`	`"sm" \| "md" \| "lg"`	`md`	Density scale.	No
`className`	`string`	none	No description in the contract.	No

Variants

Available sizes: sm, md, lg (default md).

Invalid combinations

MUST NOT: selectedId and defaultSelectedId set together. selectedId makes the component controlled and defaultSelectedId uncontrolled; pass one, not both.
MUST NOT: expandedIds and defaultExpandedIds set together. expandedIds makes the component controlled and defaultExpandedIds uncontrolled; pass one, not both.

Keyboard

TreeView keyboard behaviour
Key	Behaviour
ArrowUp	Moves focus or the value in that direction. (standard)
ArrowDown	Moves focus or the value in that direction. (standard)
ArrowLeft	Moves focus or the value in that direction. (standard)
ArrowRight	Moves focus or the value in that direction. (standard)
Home	Moves to the first item. (standard)
End	Moves to the last item. (standard)
Enter	Activates the focused control. (standard)
Space	Activates or toggles the focused control. (standard)

Rows marked (standard) name a key the contract lists without a description; the behaviour shown is the usual one for that key.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

TreeView rules
Level	Rule	How it is checked
MUST NOT	`selectedId` and `defaultSelectedId` set together. `selectedId` makes the component controlled and `defaultSelectedId` uncontrolled; pass one, not both.	Checked by the MCP tool validate_component_usage.
MUST NOT	`expandedIds` and `defaultExpandedIds` set together. `expandedIds` makes the component controlled and `defaultExpandedIds` uncontrolled; pass one, not both.	Checked by the MCP tool validate_component_usage.
MUST	ARIA: Root has role=tree and an accessible name.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Nodes expose role=treeitem, aria-level and aria-selected.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Branch nodes expose aria-expanded.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Only the focused treeitem has tabIndex=0.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-07-26.
SHOULD	Give the tree an accessible label that identifies the hierarchy.	Not stated in the contract.
SHOULD	Use stable node identifiers across filtering, refreshes, and reordering.	Not stated in the contract.
SHOULD	Keep labels concise and place secondary status in the description.	Not stated in the contract.
SHOULD	Preserve expansion state when nearby application content changes.	Not stated in the contract.
SHOULD NOT	Do not embed buttons, inputs, or menus inside a tree item's label.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { TreeView } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/navigation exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.