Web TreeView Showcase

TR01 Properties

All available properties for the Web TreeView component

Property Reference

Attribute / Property	Type	Default	Description
`data*` (JS only)	`Array<object>`	`[]`	Array of tree node objects with hierarchical structure. Set via JS property.
`id-member` / `idMember`	`string`	`'id'`	Property name for unique node identifiers
`path-member` / `pathMember`	`string`	`'path'`	Property name for hierarchical path structure
`display-value-member` / `displayValueMember`	`string`	`'displayValue'`	Property name for displayed node text
`expand-level` / `expandLevel`	`number`	`2`	Default expansion depth for tree nodes
`should-toggle-on-node-click` / `shouldToggleOnNodeClick`	`boolean`	`false`	Enable expand/collapse on node click
`drag-drop-mode` / `dragDropMode`	`string`	`'none'`	Controls drag-drop: 'none' \| 'cross' \| 'both'
`sortCallback` (JS only)	`function`	`null`	Custom sorting function for tree nodes
`search-text` / `searchText`	`string`	`''`	Search query string for filtering nodes
`virtual-scroll` / `virtualScroll`	`boolean`	`false`	Enable virtual scroll rendering for large trees
`progressive-render` / `progressiveRender`	`boolean`	`true`	Render nodes progressively in batches

* Required properties | Attributes use kebab-case, JS properties use camelCase

Usage Examples

Property Usage

Property Details

Required Properties

The core required properties define the data structure:

data: Array of your tree objects (set via JS)
id-member: Unique identifier field name
path-member: Hierarchical path field name
display-value-member: Display text field name

Path Structure

Uses LTree-inspired paths like "1", "1.1", "1.1.1" for hierarchy.

Search Integration

Built-in search with search-text attribute or searchText property.

TR02 Render Callbacks

Customizable render callbacks for advanced content

Available Callbacks

Callback	Purpose	Parameters
`renderNodeCallback`	Custom node display content	`(node, container: HTMLElement)`
`renderEmptyStateCallback`	Custom empty tree message	`(container: HTMLElement)`
`renderHeaderCallback`	Custom tree header	`(container: HTMLElement)`
`renderFooterCallback`	Custom tree footer	`(container: HTMLElement)`

Callback Usage

Custom Render Callbacks

Customization Guide

Node Content

Override default node rendering with custom HTML, icons, badges, and interactive elements via renderNodeCallback.

Empty State

Show custom content when the tree has no data using renderEmptyStateCallback.

Header / Footer

Add custom header and footer content above and below the tree nodes.

Context Menu

Use renderContextMenuCallback for fully custom context menu rendering.

TR03 Context Menu API

Right-click context menus with callback approach

Context Menu Properties

Property	Type	Default	Description
`contextMenuCallback`	`(node, closeMenuCallback) => ContextMenuEntry[]`	`null`	Function returning context menu items for dynamic menus. Receives `closeMenuCallback` parameter.
`context-menu-x-offset`	`number`	`8`	Horizontal offset from cursor position (px)
`context-menu-y-offset`	`number`	`0`	Vertical offset from cursor position (px)
`should-display-context-menu-in-debug-mode`	`boolean`	`false`	Show persistent debug context menu at fixed position

ContextMenuItem Interface

Property	Type	Required	Description
`icon`	`string`	Optional	Icon or emoji for menu item
`title`	`string`	Optional	Display text for menu item
`callback`	`() => void \| Promise<void>`	Optional	Sync or async function to execute
`isDisabled`	`boolean`	Optional	Disable menu item interaction
`isDivider`	`boolean`	Optional	Render as visual separator line
`className`	`string`	Optional	CSS classes for custom styling

Async Callback Support:

Promise Support: Menu callbacks can return Promise<void>
Automatic Error Handling: Failed async operations are caught and logged automatically
Enhanced Menu Control: Callbacks receive closeMenuCallback parameter for programmatic control

Context Menu Usage

Context Menu Implementation

Context Menu Features

Callback-Based Approach

contextMenuCallback: Dynamic, type-safe, recommended for most cases
renderContextMenuCallback: Full control, custom layouts, advanced styling

Async Callback Features

Promise Support: Return Promise<void> from callbacks
Error Handling: Automatic try/catch wrapper with console logging
Menu Control: Optional closeMenuCallback parameter
Robustness: Menu stays open on errors for user retry

Position Control

Fine-tune menu positioning with X/Y offset properties for optimal cursor clearance.

Debug Mode

Use should-display-context-menu-in-debug-mode for persistent menu display during development.

TR04 Events

CustomEvent-based event handling for user interactions

Available Events

Event / Callback	Trigger	Detail
`onNodeClicked`	User clicks on a node	`(node: TreeNode<T>) => void`
`onNodeDragStart`	Drag operation begins	`(node, event: DragEvent) => void`
`onNodeDragOver`	Dragging over a node	`(node, event: DragEvent) => void`
`onNodeDrop`	Drop operation completes	`(dropNode, draggedNode, position, event, operation)`

Note: Callbacks are set as JS properties: tree.onNodeClicked = handler. The component also dispatches CustomEvents (e.g. node-clicked) on the host element.

Event Usage

Event Handling

Event Details

User Interactions

Use onNodeClicked to handle clicks on tree nodes.

Drag and Drop

Use onNodeDrop with position and operation parameters for full control.

onNodeDrop Params

position: 'above' | 'below' | 'child'
operation: 'move' | 'copy'
dropNode: null for root drops

Two Approaches

Set callbacks as JS properties, or use addEventListener with CustomEvent names (kebab-case).

TR05 Public Methods

Tree manipulation methods for programmatic control

Method Reference

Method	Returns	Description
`addNode(parentPath, data, pathSegment?)`	`AddNodeResult`	Add a new node under the specified parent
`moveNode(sourcePath, targetPath, position)`	`MoveNodeResult`	Move a node to a new location
`removeNode(path)`	`RemoveNodeResult`	Remove a node and its descendants
`updateNode(path, changes)`	`UpdateNodeResult`	Update node data properties
`copyNodeWithDescendants(node, parentPath, transformer)`	`CopyResult`	Deep copy a node subtree with data transformation
`getNodeByPath(path)`	`TreeNode \| null`	Get a node by its path
`getChildren(parentPath)`	`TreeNode[]`	Get direct children of a node
`getSiblings(path)`	`TreeNode[]`	Get siblings of a node
`getAllData()`	`T[]`	Extract all node data for persistence
`getExpandedPaths()`	`string[]`	Get currently expanded node paths
`setExpandedPaths(paths)`	`void`	Restore expanded state after data reload
`expandNodes(path)` / `collapseNodes(path)`	`void`	Expand/collapse a specific node
`expandAll()` / `collapseAll()`	`void`	Expand/collapse all nodes
`scrollToPath(path, options?)`	`void`	Scroll to and highlight a node

Note: Methods highlighted in blue are tree editor methods for CRUD operations.

Usage Examples

Tree Editor Methods

Implementation Guide

CRUD Operations

Use addNode, updateNode, removeNode for direct tree manipulation without full data reload.

Move Operations

moveNode accepts position: 'above' | 'below' | 'child' to control placement.

State Preservation

Use getExpandedPaths / setExpandedPaths to preserve UI state across data reloads.

Batch Operations

getAllData() extracts all node data for batch database saves.

Result Objects

All CRUD methods return result objects with:

success: boolean
node?: TreeNode (the affected node)
error?: string (if failed)

TR06 Usage Examples

Common implementation patterns and use cases

Live Example

Complete Code

File System Tree

Implementation Notes

File System Pattern

Common pattern for displaying folder structures with custom sorting to show folders before files.

Key Features Used

Custom sort callback
Click to expand/collapse
Multi-level expansion
Type-based organization

Customization Tips

Add icons, badges, or context menus using the renderNodeCallback for enhanced UX.

TR07 Accessibility

Built-in accessibility features and best practices

Accessibility Features

Keyboard Navigation
Arrow keys, Enter, Space for full navigation

ARIA Tree Pattern
Proper tree, treeitem, and group roles

Screen Reader Support
aria-expanded, aria-selected, aria-level

Focus Management
Visible focus indicators and proper tab order

ARIA Implementation

ARIA Structure

Accessibility Guide

Keyboard Shortcuts

Up/Down Navigate between nodes
Left/Right Expand/collapse nodes
Enter Activate/select node
Space Toggle selection
Home/End First/last node

Screen Readers

Announces node names, levels, expansion state, and selection status automatically.

High Contrast

Focus indicators work with Windows High Contrast mode and respect user preferences.