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";Basic (single select)
Loading interactive example…
View source
<script lang="ts"> import { TreeView } from "phoundry-ui"; import type { TreeNode } from "phoundry-ui";
const fileTree: TreeNode[] = [ { id: "src", label: "src", icon: "carbon:folder", children: [ { id: "src/lib", label: "lib", icon: "carbon:folder", children: [ { id: "src/lib/index.ts", label: "index.ts", icon: "carbon:document", }, { id: "src/lib/utils.ts", label: "utils.ts", icon: "carbon:document", }, ], }, { id: "src/routes", label: "routes", icon: "carbon:folder", children: [ { id: "src/routes/+page.svelte", label: "+page.svelte", icon: "carbon:document", }, { id: "src/routes/+layout.svelte", label: "+layout.svelte", icon: "carbon:document", }, ], }, ], }, { id: "package.json", label: "package.json", icon: "carbon:document" }, { id: "README.md", label: "README.md", icon: "carbon:document" }, ];
let basicSelected = $state<string[]>([]);</script>
<div class="max-w-xs"> <TreeView nodes={fileTree} selected={basicSelected} onselect={(ids: string[]) => { basicSelected = ids; }} /></div><p class="mt-2 text-xs text-txt-tertiary"> Selected: {basicSelected.length ? basicSelected.join(", ") : "none"}</p>Multi-select
Loading interactive example…
View source
<script lang="ts"> import { TreeView } from "phoundry-ui"; import type { TreeNode } from "phoundry-ui";
const fileTree: TreeNode[] = [ { id: "src", label: "src", icon: "carbon:folder", children: [ { id: "src/lib", label: "lib", icon: "carbon:folder", children: [ { id: "src/lib/index.ts", label: "index.ts", icon: "carbon:document", }, { id: "src/lib/utils.ts", label: "utils.ts", icon: "carbon:document", }, ], }, { id: "src/routes", label: "routes", icon: "carbon:folder", children: [ { id: "src/routes/+page.svelte", label: "+page.svelte", icon: "carbon:document", }, { id: "src/routes/+layout.svelte", label: "+layout.svelte", icon: "carbon:document", }, ], }, ], }, { id: "package.json", label: "package.json", icon: "carbon:document" }, { id: "README.md", label: "README.md", icon: "carbon:document" }, ];
let multiSelected = $state<string[]>([]);</script>
<p class="mb-2 text-xs text-txt-secondary"> Cmd/Ctrl-click toggles; Shift-click extends the range from the last selection.</p><div class="max-w-xs"> <TreeView nodes={fileTree} selected={multiSelected} onselect={(ids: string[]) => { multiSelected = ids; }} multiSelect /></div><p class="mt-2 text-xs text-txt-tertiary"> Selected: {multiSelected.length ? multiSelected.join(", ") : "none"}</p>Controlled expanded state
Loading interactive example…
View source
<script lang="ts"> import { TreeView } from "phoundry-ui"; import type { TreeNode } from "phoundry-ui";
const fileTree: TreeNode[] = [ { id: "src", label: "src", icon: "carbon:folder", children: [ { id: "src/lib", label: "lib", icon: "carbon:folder", children: [ { id: "src/lib/index.ts", label: "index.ts", icon: "carbon:document", }, { id: "src/lib/utils.ts", label: "utils.ts", icon: "carbon:document", }, ], }, { id: "src/routes", label: "routes", icon: "carbon:folder", children: [ { id: "src/routes/+page.svelte", label: "+page.svelte", icon: "carbon:document", }, { id: "src/routes/+layout.svelte", label: "+layout.svelte", icon: "carbon:document", }, ], }, ], }, { id: "package.json", label: "package.json", icon: "carbon:document" }, { id: "README.md", label: "README.md", icon: "carbon:document" }, ];
let basicSelected = $state<string[]>([]);
let expandedControlled = $state<string[]>(["src"]);</script>
<p class="mb-2 text-xs text-txt-secondary"> Keep <code>expanded</code> in your store so folders stay open across navigations.</p><div class="max-w-xs"> <TreeView nodes={fileTree} selected={basicSelected} bind:expanded={expandedControlled} onselect={(ids: string[]) => { basicSelected = ids; }} /></div><p class="mt-2 text-[11px] text-txt-tertiary"> Expanded IDs: {expandedControlled.join(", ") || "(none)"}</p>Virtual scroll
Loading interactive example…
View source
<script lang="ts"> import { TreeView } from "phoundry-ui"; import type { TreeNode } from "phoundry-ui";
const flatChildren: TreeNode[] = Array.from({ length: 60 }, (_, i) => ({ id: `big-${i}`, label: `item-${i}.ts`, icon: "carbon:document", }));
const bigTree: TreeNode[] = [ { id: "big-root", label: "large-folder", icon: "carbon:folder", children: flatChildren, }, ];
let vsExpanded = $state<string[]>(["big-root"]);
let vsSelected = $state<string[]>([]);</script>
<p class="mb-2 text-xs text-txt-secondary"> Enable <code>virtualScroll</code> when an expanded branch can contain hundreds of rows. Set <code>maxHeight</code> so the tree gets a scrollable viewport.</p><TreeView nodes={bigTree} selected={vsSelected} bind:expanded={vsExpanded} onselect={(ids: string[]) => { vsSelected = ids; }} virtualScroll maxHeight={220} itemHeight={28} class="rounded-lg border border-border-muted"/>API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
nodesrequired | TreeNode<T>[] | — | Root nodes of the tree. |
selectedbindable | string[] | [] | Selected node IDs. Bindable when you need two-way updates. |
expandedbindable | 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 | ClassValue | '' | Classes on the scroll container. |
nodeContent | Snippet<[node: TreeNode<T>, depth: number, isExpanded: boolean, isSelected: boolean]> | — | Replace default label/icon row for a node. |
TreeNode
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
idrequired | string | — | Unique node identifier. |
labelrequired | 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
nodeContentwhen you need badges, secondary lines, or actions inside each row while keeping expand/collapse behavior. - Set
showIndentGuides={false}for a flatter explorer-style list. disabledon 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).
CSS styling
.ph-tree-view is the stable identification hook for TreeView. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
Row selection and expansion use aria-selected and aria-expanded; variants use data-variant. Virtualization and pixel-based row/indent measurements are unchanged.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.