Data Display

TreeItem

Node within a tree that exposes a label, optional children, and expand and selection state through the tree context.

import { TreeItem } from '@lostgradient/cinder/tree-item';
treenode
01

Overview

Expandable or leaf node within a tree view for hierarchical data navigation.

Usage

TreeItem is a compose-only leaf of Tree. The idiomatic API is Tree.Item, reached through the parent namespace — see the tree README for the composed snippet. The flat @lostgradient/cinder/tree-item subpath remains exported for à-la-carte builds that import the leaf directly.

02

When to use

Use when
  • Rendering a single branch or leaf inside a tree parent.
  • Nesting further tree-items as children to form a hierarchy.
Avoid when
  • Standing alone outside a tree — it requires the tree context and registry.
03

Props

Props for tree-item
Name Type Default Required Bindable Description
id text req Stable unique id within the tree.
label text req Accessible name for the item. Also used as the typeahead key.
disabled boolean false When true, the item cannot be selected or actioned. Still keyboard-reachable.
draggable boolean false Render a reorder handle when the parent Tree provides onReorder.
branch boolean false Marks the node as an expandable branch. A node is a leaf unless it sets branch or loadChildren; supplying a children snippet alone is not enough. Marking the node as a branch lets the tree render the correct expand affordance and aria-expanded state before any children exist (for example, before an async loadChildren resolves).
loadChildren (context: { id: string; signal: AbortSignal }) => voidPromise<void> Async loader called the first time the item is expanded. Implies branch=true. The loader mutates consumer-owned reactive state; it returns no data. Errors are forwarded to onLoadError if provided, otherwise logged via console.error with a [cinder-tree] prefix.
onLoadError (error: unknown, itemId: string) => void Called when loadChildren rejects with a non-abort error.
onRename (itemId: string, nextLabel: string) => voidPromise<void> Called when inline label editing commits a new label.
selectionScopeIds string[] Explicit selectable ids controlled by this item in cascade checkbox-selection mode.
row snippet Optional row content snippet override. Default renders label.
children snippet Nested TreeItem children for branch nodes.