Data Display

Tree

Composite root that renders a hierarchical tree of tree-item nodes with keyboard navigation and selection state.

import { Tree } from '@lostgradient/cinder/tree';
treehierarchy
01

Overview

Hierarchical tree view for navigating or selecting nested data structures.

Usage

Tree is a compound component. Import the parent and compose Tree.Item via the namespace API.

svelte 
<script lang="ts">
  import { Tree } from '@lostgradient/cinder/tree';

  let expandedIds = $state<string[]>(['fruit']);
</script>

<Tree aria-label="Pantry" bind:expandedIds>
  <Tree.Item id="fruit" label="Fruit" branch>
    <Tree.Item id="apple" label="Apple" />
    <Tree.Item id="banana" label="Banana" />
  </Tree.Item>
  <Tree.Item id="grain" label="Grain" branch>
    <Tree.Item id="rice" label="Rice" />
  </Tree.Item>
</Tree>

The leaf remains importable individually for à-la-carte builds — see @lostgradient/cinder/tree-item.

Live preview
02

When to use

Use when
  • Presenting hierarchical data such as a file system, organization, or nested categories.
  • Coordinating single- or multi-select state across all descendant tree-items via the selectionMode prop.
Avoid when
03

Examples

Basic tree

A small hierarchy with one branch expanded. Uses the Tree namespace API: Tree.Item composes inside the parent Tree.

Cascading toggle

Branch activation can opt into selecting or clearing the branch and its explicit selection scope.

File explorer multi-select

A file-tree pattern with checkbox indicators, a root-level select-all control, and bindable selected ids.

Indeterminate parents

Parent checkbox indicators move to mixed state when only part of their selection scope is selected.

Long labels and narrow widths

Long item labels truncate with an ellipsis rather than forcing the tree wider than its container. The full text stays available to assistive tech via the visually-hidden label. Resize narrow to see truncation; rows keep a comfortable touch target.

Drag reorder

Draggable tree items emit a consumer-owned reorder target. The example records the last drop so pointer behavior can be verified.

Virtualized tree

A data-driven tree renders a small window from a 10,000-item collection while preserving full aria-posinset and aria-setsize metadata.

04

Props

Props for tree
NameTypeDefaultDescription
selectionMode 'none' | 'single' | 'multiple' 'none' Selection model. Default: 'none'.
checkboxSelection boolean false Render tree-owned checkbox indicators when selectionMode is multiple. Default: false.
selectionBehavior 'independent' | 'cascade' 'independent' Select only the target item or cascade through its selectable scope. Default: 'independent'.
selectedIds bindable string[] [] Currently selected node ids. Bindable.
expandedIds bindable string[] [] Currently expanded branch ids. Bindable.
ref bindable { /** Expand every currently discoverable static branch. */ expandAll: () => Promise<void>; /** Collapse every expanded branch with a single expandedIds u…
Show full type { /** Expand every currently discoverable static branch. */ expandAll: () => Promise<void>; /** Collapse every expanded branch with a single expandedIds update. */ collapseAll: () => void; /** Expand only the currently visible static branch level. */ expandOneLevel: () => void; /** Focus a visible registered item by id. Unknown or hidden ids are ignored. */ focusItem: (id: string) => void; /** Expand registered ancestors for an item, then focus it if it is visible. */ expandToItem: (id: string) => Promise<void>; /** Scroll a registered row into view. Unknown ids are ignored. */ scrollToRow: (id: string, options?: ScrollIntoViewOptions) => void; }
 Typed programmatic handle. Use bind:ref to receive it.
items TreeDataItem[] Data-driven Tree items. Required when virtualized is true; mutually exclusive with children.
virtualized false | undefined false Use the data-driven virtualized render path for large trees. Default: false.
virtualizationEstimatedRowHeight number 36 Estimated row height for virtualized Tree rows. Default: 36.
virtualizationOverscan number 4 Extra rows rendered before and after the viewport. Default: 4.
virtualizationHeight number '20rem' Block size for the virtualized scroll viewport. Default: '20rem'.
virtualizedItem snippet Optional custom virtualized row renderer.
typeaheadDisabled boolean false Disable typeahead.
id text
style text
selectionControls snippet Optional selection controls rendered before the role="tree" element.
filterValue text Controlled filter query. When provided, matching is driven by this value.
onFilterChange (value: string) => void Fires whenever the built-in search input changes the filter query.
filterPlaceholder text 'Search tree' Placeholder and accessible label for the built-in search input. Default: 'Search tree'.
searchVisible boolean false Render the built-in search input before the role="tree" element. Default: false.
filterPredicate (label: string, id: string, query: string) => boolean Custom filter predicate. Default: case-insensitive label substring matching.
onReorder (draggedId: string, target: TreeReorderTarget) => void Called when a draggable item is dropped before, after, or into another tree item.
children required snippet Tree items (snippet). Required when virtualized is false or omitted; mutually exclusive with items.