Skip to content

Design system

Documentation

DesignComponents / Tree

Components / Tree

Stable

Tree

Navigate and select hierarchical items with expansion and keyboard behavior.

On this page

Examples

Expandable hierarchy

Arrow keys move through visible nodes; Right and Left expand or return to a parent.

Engineering
Frontend
Platform

Company teams tree

Multiple selection

Select several nodes while keeping the expansion state separate.

Engineering
Frontend
Platform
Design

Multiple-selection tree

Unavailable node

A disabled node remains readable but cannot be selected.

Active project
Archived project

Tree with a disabled project

Large visible tree

Trees with more than 200 visible items use a bounded virtual window while preserving active-descendant navigation.

Department 1
Department 2
Department 3
Department 4
Department 5
Department 6
Department 7
Department 8
Department 9
Department 10
Department 11
Department 12
Department 13
Department 14
Department 15

Virtualized tree with 250 departments

Try the tree

Inspect an expandable navigation hierarchy.

Workspace
Projects
Settings

Tree property playground

Usage

import { Tree } from "@phuctech/ui/components/tree";

<Tree label="Company teams" nodes={teamTree} defaultExpandedKeys={["engineering"]} />

Behavior

  • The tree container uses one tab stop and keeps the active item in aria-activedescendant.
  • Up/Down move through visible nodes; Home/End move to the first/last visible node.
  • Right expands a closed branch or enters its first child. Left collapses a branch or moves to its parent.
  • Enter or Space selects the active item. A disabled node is readable and expandable but cannot be selected.
  • Expansion and selection each support controlled and uncontrolled state. When more than 200 items are visible, Tree renders a fixed 36px-row virtual window inside a bounded 24rem scroll region; keyboard navigation scrolls the active item into view.

API

Component API
PropTypeDefaultDescriptionConstraints
labelstringrequiredAccessible tree name.Use a visible heading or specific aria label.
nodesreadonly TreeNode[]requiredNested nodes with stable unique IDs and labels.Set textValue when labels are not plain text and need a searchable string.
selectionMode"single" | "multiple" | "none""single"Controls whether nodes can be selected.Disabled nodes cannot be selected.
selectedKeys / defaultSelectedKeysreadonly string[][]Controlled selection or its initial value.Use node IDs and do not mix controlled and uncontrolled state.
onSelectionChange(keys: readonly string[]) => void—Receives the complete next selection.The feature owns what selection means.
expandedKeys / defaultExpandedKeysreadonly string[][]Controlled expansion or its initial value.Use IDs of branches that have children.
onExpandedKeysChange(keys: readonly string[]) => void—Receives the next expanded branch set.The feature owns persistence and lazy-loading decisions.
disabledbooleanfalsePrevents tree selection and keyboard interaction.A disabled node remains available for reading.

Accessibility

Small trees use nested treeitem and group roles; virtualized trees expose flat treeitem rows with aria-level, aria-posinset, and aria-setsize. Both modes keep the active descendant mounted and expose a node-specific disclosure name. Expansion remains separate from selection.

  • TreeSelect places the same hierarchy inside a searchable selection popup.
  • Cascader selects one path when only one level should be visible at a time.