TreeView

Hierarchical tree with expand/collapse, single or multi-selection, keyboard navigation, optional virtual scrolling for large lists, and custom row rendering.

import { TreeView } from 'phoundry-ui';
import type { TreeNode } from 'phoundry-ui';

Usage: Focus the tree and use arrow keys to move; →/← expand or collapse branches; * expands all siblings at the current depth. There are no built-in checkboxes — selection is highlight-based; pair with your own UI if you need explicit checkbox affordances.

Basic (single select)

src

package.json

README.md

Selected: none

Show code

<TreeView
  nodes={fileTree}
  bind:selected={selectedIds}
  onselect={(ids) => (selectedIds = ids)}
/>

Multi-select

Cmd/Ctrl-click toggles; Shift-click extends the range from the last selection.

src

package.json

README.md

Selected: none

Show code

<TreeView
  nodes={fileTree}
  bind:selected={selectedIds}
  multiSelect
/>

Controlled expanded state

Keep expanded in your store so folders stay open across navigations.

src

lib

routes

package.json

README.md

Expanded IDs: src

Show code

<TreeView
  nodes={fileTree}
  bind:expanded={openFolders}
  bind:selected={selectedIds}
/>

Virtual scroll

Enable virtualScroll when an expanded branch can contain hundreds of rows. Set maxHeight so the tree gets a scrollable viewport.

Show code

<TreeView
  nodes={manyChildrenUnderOneFolder}
  bind:expanded={expanded}
  bind:selected={selected}
  virtualScroll
  maxHeight={220}
  itemHeight={28}
/>

Props

Prop	Type	Default	Description
nodes required	TreeNode<T>[]	—	Root nodes of the tree.
selected	string[]	—	Selected node IDs. Bindable when you need two-way updates.
expanded	string[]	—	Expanded branch node IDs. Bindable for controlled expand/collapse.
onselect	(ids: string[]) => void	—	Called when selection changes (click or keyboard).
onexpand	(ids: string[]) => void	—	Called when expanded set changes.
onactivate	(node: TreeNode<T>) => void	—	Called on double-click on a node, or Enter on a leaf/focused row (see implementation).
multiSelect	boolean	false	Cmd/Ctrl-click toggles selection; Shift-click selects ranges.
showIndentGuides	boolean	true	Vertical guide lines for depth.
indentWidth	number	20	Pixels per depth level for indentation.
itemHeight	number	28	Row height in px (also used with virtual scrolling).
virtualScroll	boolean	false	Window rendering for large flat lists under expanded branches.
maxHeight	number	—	Optional max height in px; inner area scrolls.
class	string	—	Classes on the scroll container.
nodeContent	Snippet<[TreeNode<T>, depth, isExpanded, isSelected]>	—	Replace default label/icon row for a node.

TreeNode

Prop	Type	Default	Description
id required	string	—	Unique node identifier.
label required	string	—	Display text.
icon	string	—	Iconify icon string.
children	TreeNode<T>[]	—	Child nodes.
data	T	—	Opaque payload on the node.
disabled	boolean	—	Exclude from selection and gray out.

Usage tips

Use nodeContent when you need badges, secondary lines, or actions inside each row while keeping expand/collapse behavior.
Set showIndentGuides={false} for a flatter explorer-style list.
disabled on a node prevents selection and dims the row; expand chevrons remain for folders unless you hide them via custom content.
Icons use Iconify strings (same as elsewhere in the library).