Skip to content

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
basic-single-select.svelte
<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
multi-select.svelte
<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
controlled-expanded-state.svelte
<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
virtual-scroll.svelte
<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

NameTypeDefaultDescription
nodesrequiredTreeNode<T>[]—Root nodes of the tree.
selectedbindablestring[][]Selected node IDs. Bindable when you need two-way updates.
expandedbindablestring[][]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).
multiSelectbooleanfalseCmd/Ctrl-click toggles selection; Shift-click selects ranges.
showIndentGuidesbooleantrueVertical guide lines for depth.
indentWidthnumber20Pixels per depth level for indentation.
itemHeightnumber28Row height in px (also used with virtual scrolling).
virtualScrollbooleanfalseWindow rendering for large flat lists under expanded branches.
maxHeightnumber—Optional max height in px; inner area scrolls.
classClassValue''Classes on the scroll container.
nodeContentSnippet<[node: TreeNode<T>, depth: number, isExpanded: boolean, isSelected: boolean]>—Replace default label/icon row for a node.

TreeNode

From phoundry-ui@0.4.21

NameTypeDefaultDescription
idrequiredstring—Unique node identifier.
labelrequiredstring—Display text.
iconstring—Iconify icon string.
childrenTreeNode<T>[]—Child nodes.
dataT—Opaque payload on the node.
disabledboolean—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).

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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.