Data Structure Requirements

• Unique IDs: Each node must have a unique identifier
• Path Hierarchy: Use dot notation like "1.2.3" for parent-child relationships
• Flat Array: All nodes in a single array, not nested objects

Path Format Examples

• "1" - Root level node
• "1.1" - Child of node "1"
• "1.1.1" - Grandchild of node "1"
• "2.5.3" - Third child of fifth child of second root

Performance Notes

The component efficiently handles large datasets using the LTree structure for fast hierarchy lookups.

CSS Variables

All CSS variables use the --tv- prefix. Set them on the web-treeview element or a parent container.

Custom Themes

Use the various class properties and CSS variables to implement custom themes, dark modes, or brand-specific styling.

Toggle Icon Modes

• rotate (default) - Uses expandIconClass only, CSS rotates 90deg
• swap - Swaps between expandIconClass and collapseIconClass

Shadow DOM Styling

Use customStylesCallback to inject CSS into the Shadow DOM for deep customization.

Drag and Drop

Set drag-drop-mode="both" to enable drag-drop. Use getIsDraggableCallback for per-node control.

Flexible Search

Customize what's searchable with getSearchValueCallback. The tree automatically filters to show matching nodes and their ancestors.

Dynamic Sorting

Sort callbacks receive tree nodes with access to original data via node.data. Useful for sorting by dates, types, or custom criteria.

Performance Tips

Callbacks are called frequently - keep them lightweight and avoid expensive operations.

Drop Positions

When dropping a node, the position parameter indicates:

• 'above' - Insert as sibling before target
• 'below' - Insert as sibling after target
• 'child' - Insert as child of target

Touch Support

Touch drag-drop is enabled by default:

• Long-press (300ms) initiates drag
• Ghost element follows finger
• Haptic feedback on drag start

Loading State

Use is-loading attribute or isLoading property to show a visual overlay during async operations.

Empty Tree Drops

Use renderEmptyZoneCallback to create custom drop targets for empty trees.

Exponential Batching

Batches grow: 20 -> 40 -> 80 -> 160 -> 320 -> 500 (capped). For 5000 nodes, this means ~8 batches instead of 25 with fixed sizing.

Performance Impact

• Progressive: Instant first 20 nodes, smooth fill-in
• Virtual scroll: Only renders visible rows, handles 100K+ nodes
• UI: Remains responsive during rendering

Virtual Scroll

Enable virtual-scroll for datasets with thousands of nodes. Only visible rows plus overscan are rendered in the DOM.

Choosing a Mode

• Small trees (<500): Default progressive rendering
• Large trees (500-5000): Progressive with tuned batch sizes
• Huge trees (5000+): Virtual scroll

Two Approaches

onNodeDrop Parameters

• position: 'above' | 'below' | 'child'
• operation: 'move' | 'copy'
• dropNode: null for root/empty tree drops

Async beforeDropCallback

Validate or modify drops with async support:

• Return false to cancel the drop
• Return true to allow
• Return { position: 'below' } to override position
• Supports async/await for confirmation dialogs