Component

Tree

Recursive expandable tree with roving-tabindex keyboard navigation, for file browsers and nested navigation. Each node takes an id, label, optional icon, and optional children.

Basic

Nodes with children render an expand/collapse toggle; leaf nodes don't.

src

components

index.ts

assets

README.md

Arrow Right expands a node (or moves to its first child if already expanded); Arrow Left collapses it (or moves to its parent)
Only one node is a Tab stop at a time - a roving tabindex, the same pattern Sidebar and Rating use

Default expanded

defaultExpandedIds pre-opens specific branches on first render, without making the tree controlled.

src

components

Button.tsx

Card.tsx

index.ts

assets

logo.svg

README.md

Controlled selection

selectedId plus onSelect drives the selected node from your own state - onSelect fires on click or Enter/Space while a node is focused.

src

components

Button.tsx

Card.tsx

index.ts

assets

README.md

Selected: button.tsx

When to use

A file/folder browser or any genuinely nested, collapsible hierarchy the user navigates by drilling down.
Nested navigation where parent/child relationships matter and the full structure benefits from being collapsible.

When not to use

Flat navigation with no real hierarchy - use Sidebar, which is lighter and has no expand/collapse state to manage.
A single level of grouped links - Sidebar.Section already groups without needing recursive nodes.

Keyboard

Key	Action
Arrow Up / Down	Moves focus to the previous/next visible node.
Arrow Right	Expands a collapsed node, or moves to its first child if already expanded.
Arrow Left	Collapses an expanded node, or moves to its parent if already collapsed.
Enter / Space	Activates the focused node, firing onSelect.

Mobile behavior

Each node keeps a touch-friendly row height, and the expand/collapse toggle is part of the same tappable row rather than a separate small hit target.

Accessibility notes

Follows the ARIA treeview pattern with a roving tabindex - only the focused node is a Tab stop.
Expand/collapse state is exposed via aria-expanded on parent nodes.

Common mistakes

Passing a new data array with different node identities on every render - keep the tree data stable (e.g. in state or a constant) so expanded/selected state doesn't reset unexpectedly.
Using Tree for a flat list with no real parent/child relationship - Sidebar or List is simpler.

Known limitations

No built-in drag-to-reorder, lazy/async node loading, or multi-select - selection is single-node via selectedId.

Related components

Sidebar

Criterion	Status	Note
Keyboard support	Supported	Full ARIA treeview arrow-key navigation plus Enter/Space activation.
Focus management	Supported	Roving tabindex keeps exactly one node in the tab order.
Screen reader labels	Supported	Node text is the accessible name; aria-expanded reflects branch state.
Reduced motion	Supported	Expand/collapse uses the shared Fuji UI duration tokens, which zero under prefers-reduced-motion.
Reduced transparency	Not applicable	Uses opaque surfaces in every theme.
Mobile touch behavior	Supported	Each row meets a touch-friendly height; verified down to 320px.

API reference

Prop	Type	Default	Description
data *	TreeNode[]	None	The roots of the tree.
defaultExpandedIds	string[]	[]	`id`s expanded on first render. Expansion is uncontrolled from then on.
expandOnSelect	boolean	true	Whether selecting a parent node also toggles it. Default `true`. `false` (WAI-ARIA tree): select only; the chevron or ArrowRight/Left toggles. Use when a folder is itself selectable.
onSelect	((node: TreeNode) => void)	None	Fires when a tree node is activated (click, or Enter/Space while focused) - unrelated to the native `onSelect` text-selection event.
selectedId	string	None	`id` of the selected node. Controlled - the tree does not track selection itself.

data *None

TreeNode[]

The roots of the tree.

defaultExpandedIds[]

string[]

`id`s expanded on first render. Expansion is uncontrolled from then on.

expandOnSelecttrue

boolean

Whether selecting a parent node also toggles it. Default `true`. `false` (WAI-ARIA tree): select only; the chevron or ArrowRight/Left toggles. Use when a folder is itself selectable.

onSelectNone

((node: TreeNode) => void)

Fires when a tree node is activated (click, or Enter/Space while focused) - unrelated to the native `onSelect` text-selection event.

selectedIdNone

string

`id` of the selected node. Controlled - the tree does not track selection itself.

Also accepts everything from Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect">.

Coding agents read this reference, with its examples, from the version your project has installed, through the Fuji UI MCP server. Set up your agent