EV01 Live Event Monitor

Interact with the tree to see events fired in real-time

Interactive Tree
Event Log
Event Log
0
No events yet. Interact with the tree to see events fired here.
Event Guide
How to Test Events:
  • Click nodes to trigger onNodeClicked
  • Start drag to trigger onNodeDragStart
  • Drag over nodes for onNodeDragOver
  • Drop to trigger onNodeDrop
Event Statistics:
Total events logged: 0
Log displays last 20 events
Events logged in real-time

EV02 Event Reference

All available events and callbacks for handling user interactions

Event Reference
Callback / EventTriggerSignatureDescription
onNodeClicked
node-clicked		User click(node: TreeNode<T>) => voidCalled when user clicks on any tree node
onNodeDragStart
node-drag-start		Drag begins(node, event: DragEvent) => voidCalled when user starts dragging a node
onNodeDragOver
node-drag-over		Drag over(node, event: DragEvent) => voidCalled when dragged node hovers over a target
onNodeDrop
node-drop		Drop(dropNode, draggedNode, position, event, operation) => voidExtended signature with position and operation
Two Approaches

Set callbacks as JS properties (tree.onNodeClicked = fn) or use addEventListener with kebab-case event names (tree.addEventListener('node-clicked', fn)). CustomEvent detail contains the same data.

Usage Examples
Event Handling 
 
 
Implementation Guide
 
TreeNode Structure
 
All callbacks receive TreeNode<T> objects with:
 
  • path - Node's hierarchical path
    •  
  • data - Your original data object
    •  
  • children - Child nodes map
    •  
  • isExpanded - Expansion state
    •  
  • isSelected - Selection state
 
CustomEvent Names
 
Events are dispatched with composed: true so they cross Shadow DOM boundaries. Event names use kebab-case.
 
Performance
 
  • Callbacks are invoked synchronously
    •  
  • Keep handlers lightweight
    •  
  • Debounce expensive operations
 
EV03 onNodeDrop Deep Dive
 
Extended drop callback with position and operation support
 
Full Signature
 
ParameterTypeDescription
dropNodeTreeNode<T> | nullTarget node, or null for root/empty tree drops
draggedNodeTreeNode<T>The node being dragged
position'above' | 'below' | 'child'Where to place relative to target
eventDragEvent | TouchEventOriginal browser event (supports touch)
operation'move' | 'copy'Ctrl+drag = copy operation
 
Implementation Examples
 
onNodeDrop Implementation 
 
 
 
Drop Handling Guide
 
Position Values
 
  • 'above' - Insert as sibling before target
    •  
  • 'below' - Insert as sibling after target
    •  
  • 'child' - Insert as child of target
 
Operation Types
 
  • 'move' - Default drag operation
    •  
  • 'copy' - Ctrl+drag or copy drag
 
Null dropNode
 
dropNode is null when:
 
  • Dropped on empty tree placeholder
    •  
  • Dropped on root drop zone
 
Touch Support
 
The event can be TouchEvent on mobile devices with long-press drag.
 
EV04 Search API
 
Search is property-based — use searchText property and searchNodes method
 
Search Properties & Methods
 
Property / MethodTypeDescription
search-text / searchTextstringSearch query - filters tree automatically when set
should-use-internal-search-indexbooleanEnable FlexSearch-based indexing for large trees
search-value-member / searchValueMemberstringProperty name to use for search text
getSearchValueCallback (JS only)(node) => stringCustom function to extract searchable text
searchNodes()(text: string) => TreeNode[]Method: Query nodes programmatically
filterNodes()(text: string) => voidMethod: Filter the tree display
 
Note: Property-Based Search
 
Search uses reactive properties. Set searchText and the tree filters automatically. No search events are fired.
 
Search Implementation
 
Search Implementation 
 
 
 
Search Guide
 
Reactive Filtering
 
When searchText changes, the tree automatically filters to show matching nodes and their ancestors.
 
searchNodes() Method
 
Use tree.searchNodes(query) to query nodes without changing the display filter.
 
FlexSearch Integration
 
Enable should-use-internal-search-index for optimized search on large trees.
 
Custom Indexing
 
Use getSearchValueCallback to index multiple fields or apply custom text transformations.
 
EV05 Performance & Best Practices
 
Optimize event handling for large trees and complex applications
 
Best Practices
 
Do's
 
  • Debounce expensive operations in callbacks
    •  
  • Keep callback handlers lightweight
    •  
  • Use addEventListener for multiple listeners
    •  
  • Batch state updates when handling multiple events
    •  
  • Check dropNode for null before accessing properties
 
Don'ts
 
  • Don't perform heavy computations in callbacks
    •  
  • Don't make synchronous API calls in handlers
    •  
  • Don't manipulate tree DOM directly - use the API methods
    •  
  • Don't forget to remove event listeners when component unmounts
    •  
  • Don't forget null checks for dropNode
 
Cleanup
 
If using addEventListener, remember to call removeEventListener during cleanup.
								Property callbacks (tree.onNodeClicked = null) are cleaned up automatically when the element is removed.
 
Patterns
 
Best Practices 
 
 
 
Performance Guide
 
Callback Performance
 
  • Callbacks run synchronously - keep them fast
    •  
  • Debounce API calls and heavy operations
    •  
  • Use async/await for server operations
 
Event Patterns
 
  • Property callbacks: Simple, one handler per event
    •  
  • addEventListener: Multiple handlers, standard DOM pattern
    •  
  • CustomEvents: composed: true crosses Shadow DOM
 
Large Trees
 
  • Enable should-use-internal-search-index
    •  
  • Use expand-level to limit initial render
    •  
  • Use virtual scroll for 5000+ nodes
 
Testing
 
Test event handlers by dispatching synthetic events or calling callbacks directly with mock TreeNode objects.