Overview
Use TreeView to help people inspect and navigate hierarchical data without losing the relationship between parents, children, and siblings.
Workspace hierarchy
Expand the workspace and select either project in this live preview.
Anatomy
TreeView rows combine disclosure, identifying visuals, labels, supporting metadata, status, and nested hierarchy.
- 1Disclosure
Expands or collapses a parent node without changing selection.
- 2Node icon
Helps distinguish containers, documents, and domain objects.
- 3Label and metadata
Identifies the node and adds concise supporting context.
- 4Status
Shows a count, state, or other compact supplementary value.
- 5Child group
Uses indentation and a guide to preserve parent-child relationships.
When to use
Use TreeView when hierarchy is essential to understanding or choosing an item.
Recommended
- Navigate nested resources
Use for workspaces, folders, taxonomies, organization units, or governed assets.
- Preserve visible context
Let people inspect nearby parents and siblings while moving through a hierarchy.
- Support hierarchical selection
Use when one or several nodes must be chosen from multiple levels.
When not to use
Prefer flatter patterns when hierarchy does not materially help the task.
Avoid
- Do not use for short navigation
Use Navbar, Tabs, or a simple link list for a small set of destinations.
- Do not hide unrelated categories
Use Accordion when sections are independent rather than hierarchical.
- Do not represent tabular relationships
Use DataTable when comparison across columns is the primary task.
Variants
Surface and density options adapt TreeView to navigation panels, inspectors, and contained enterprise cards.
Plain
Fits within a sidebar or panel that already provides containment.
Bordered
Defines a self-contained hierarchy on open surfaces.
Raised
Separates the hierarchy from layered or scrolling content.
Sizes
Small, medium, and large adjust density while retaining usable targets.
States
Each node communicates expansion, selection, focus, availability, and asynchronous loading independently.
| State | Trigger | Visual response | Interaction |
|---|---|---|---|
| Collapsed | Parent children are hidden | Right-pointing disclosure | Right Arrow or disclosure expands |
| Expanded | Children are visible | Downward disclosure and nested group | Left Arrow collapses |
| Selected | Node belongs to the selection | Primary-container state layer | Space toggles selection |
| Focused | Node is keyboard-active | Visible focus ring | Arrow keys move focus |
| Loading | Children are being retrieved | Progress indicator beside the node | Expansion waits for content |
| Disabled | Node is unavailable | Reduced emphasis | Discoverable but not selectable |
| Empty | No nodes are available | Named empty message | No tree navigation |
Behavior
TreeView maintains separate expansion, selection, and active-focus state so applications can control each concern independently.
Linear focus
Up and Down move through only the currently visible nodes.
Hierarchy movement
Right expands or enters children; Left collapses or returns to the parent.
Selection
Single and multiple modes update independently from disclosure.
Lazy content
Loading nodes remain stable while their children are retrieved.
Accessibility
TreeView follows the WAI-ARIA tree pattern with one active tab stop, hierarchical roles, announced selection, and complete keyboard movement.
| Key | Action |
|---|---|
| ↑↓ | Moves to the previous or next visible node. |
| → | Expands a closed parent or moves to its first child. |
| ← | Collapses an open parent or moves to its parent. |
| HomeEnd | Moves to the first or last visible node. |
| Space | Toggles selection according to selectionMode. |
| Enter | Selects and activates the focused enabled node. |
- Give the tree a concise accessible label.
- Use tree, treeitem, and group roles to preserve hierarchy.
- Expose expanded, selected, disabled, busy, position, and set-size states.
- Keep exactly one visible node in the Tab sequence.
- Do not rely on indentation or icons alone to communicate hierarchy.
- Keep disabled nodes discoverable without allowing activation.
Content guidelines
Node labels and metadata should remain short enough to scan at several levels of indentation.
Use object names
Label nodes with the resource people recognize.
Migration program
Keep siblings parallel
Use the same naming pattern for nodes at one level.
Projects, Reports, Archive
Make metadata useful
Add one short detail that helps distinguish similar items.
Updated today
Use compact badges
Reserve badges for counts or terse states.
4
Examples
Multiple selection is appropriate when people apply one operation to nodes across several branches.
Interactive workspace tree
The preview demonstrates disclosure and single selection in a compact hierarchy.
Props / API
TreeView extends div attributes; each TreeViewNode supplies identity, content, optional hierarchy, and availability state.
Props