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
Name Type Default Required Bindable Description
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 string[] [] bind Currently selected node ids. Bindable.
expandedIds string[] [] bind Currently expanded branch ids. Bindable.
ref TreeRef | undefined bind Typed programmatic handle. Use bind:ref to receive it.
items unknown req
virtualized unknown 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 | string '20rem' Block size for the virtualized scroll viewport. Default: '20rem'.
virtualizedItem snippet Optional custom virtualized row renderer.
disableTypeahead boolean false Disable typeahead. Default: false.
id unknown req
style unknown req
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 unknown req