Tree
An immutable, Signal-first hierarchy with controlled expansion, three selection models, filtering, lazy branches and virtualized visible rows.
GET STARTED
Import
Import the canonical standalone component and immutable data contracts from the granular entry point.
Controlled hierarchy
Stable keys preserve expansion and focus while application data remains immutable.
- src
- app
- app.ts
- app.html
- styles.css
- libs
- neural-ng
- neural-icons
- Remote agents
- Locked workspace
Selection models
Single, modifier-aware multiple and propagated checkbox selection share one immutable key-set contract.
Multiple ยท app-ts
- src
- app
- app.ts
- app.html
- styles.css
- libs
- neural-ng
- neural-icons
Checkbox ยท 0 selected
- src
- app
- app.ts
- app.html
- styles.css
- libs
- neural-ng
- neural-icons
Nested filtering and typed templates
Strict mode tests descendants; lenient mode keeps the complete subtree after a parent match. Nested paths never mutate source nodes.
- srcPlatform
- libsPlatform
- Remote agentsInfra
- Locked workspace
Lazy, loading, empty and retry
leaf: false declares an unloaded branch. Loading requests are guarded per key and failed branches expose an explicit retry path.
- src
Empty
Retry ยท 0
- Offline agent
Virtual range foundation
Fixed row size, viewport height and overscan compute a flat visible range compatible with the shared VirtualScroller contract.
Unstyled and typed slots
ARIA, hierarchy, keyboard navigation and lazy behavior remain; Tailwind owns every visible choice.
- src
- app
- app.ts
- app.html
- styles.css
- libs
- neural-ng
- neural-icons
TREE
Accessibility
Native focus ownership follows the WAI-ARIA Tree pattern without hiding hierarchy or asynchronous state.
ARIA model
tree, treeitem and nested group roles expose level, set size and position. Expansion, selection and checkbox mixed state are announced explicitly.
Keyboard
Arrow Up/Down move visible enabled rows. Home/End reach edges. Enter/Space selects or toggles. Printable characters run locale-aware typeahead.
Focus restore and RTL
One roving tabindex owns focus. Collapsing a focused descendant returns focus to its branch. Logical horizontal arrows reverse under RTL.
Async, SSR and cleanup
Loading, empty, error and retry states are localized. State resolution is DOM-independent; typeahead timers and lazy guards are cleaned deterministically.
TREE
API
Complete public contract for the component, controller, templates and immutable events.
Component
NeuralTree<T>neural-treeStandalone generic hierarchy renderer.
Models and inputs
| Name | Type | Default | Description |
|---|---|---|---|
| value | readonly NeuralTreeNode<T>[] | [] | Immutable hierarchical source. |
| expandedKeys | ReadonlySet<NeuralTreeKey> | new Set() | Two-way controlled expansion model. |
| selectionKeys | ReadonlySet<NeuralTreeKey> | new Set() | Two-way immutable selection model. |
| filterValue | string | '' | Two-way filter query. |
| filterMode | 'lenient' | 'strict' | 'lenient' | Matched subtree or descendant-by-descendant filtering. |
| filterFields | readonly string[] | ['label'] | Nested paths searched by the built-in filter. |
| filterPredicate | function | null | null | Custom normalized-query matcher. |
| selectionMode | 'single' | 'multiple' | 'checkbox' | null | null | Selection interaction contract. |
| metaKeySelection / rangeSelection | boolean | true | Modifier and Shift-range behavior. |
| propagateSelectionDown / Up | boolean | true | Checkbox descendant and ancestor normalization. |
| selectableNode | NeuralTreeSelectable<T> | null | null | Per-node selection gate. |
| loading | boolean | false | Localized root loading state. |
| emptyLabel / loadingLabel / retryLabel | string | null | locale | Component-level state labels. |
| ariaLabel / ariaLabelledby | string | null | null | Accessible tree naming. |
| trackBy | NeuralTreeTrackBy<T> | null | key | Custom rendering identity. |
| compact | boolean | false | Overlay-ready density. |
| virtualScroll | boolean | false | Fixed-height visible-range rendering. |
| virtualItemSize / virtualScrollHeight / virtualOverscan | number | 40 / 320 / 3 | Virtual range geometry. |
| unstyled / treeClass / classes | headless inputs | false / empty | Visual ownership and typed classes. |
Events
nodeExpand / nodeCollapse / nodeToggleNeuralTreeNodeEvent<T>Expansion lifecycle.
lazyLoadNeuralTreeLazyLoadEvent<T>One request per unloaded branch until retry.
nodeSelect / nodeUnselectNeuralTreeSelectionEvent<T>Selection result and immutable key set.
virtualRangeChangeNeuralVirtualRangeRendered range after scrolling.
Methods
expandAll()Expands every non-leaf node.
collapseAll()Collapses all branches and restores focus.
toggleNode(item, event?)Toggles a resolved visible branch.
selectNode(item, event)Applies the selection contract.
retryLazyLoad(item, event)Re-emits a failed lazy request.
visibleNode(key)Returns a current flat visible-node record.
Typed templates
neuralTreeNodeNeuralTreeNodeTemplateContext<T>
neuralTreeTogglerNeuralTreeTogglerTemplateContext<T>
neuralTreeIconNeuralTreeIconTemplateContext<T>
neuralTreeEmptyNeuralTreeStateTemplateContext
neuralTreeLoadingNeuralTreeStateTemplateContext
Typed class slots
rootlistgroupnodenodeContentselectedNodepartialNodematchedNodetogglertogglerIconnodeIconlabelcheckboxcheckboxIconloadingemptyerrorerrorMessageretryPublic types and helpers
NeuralTreeNode<T>NeuralTreeKeyNeuralTreeSelectionModeNeuralTreeCheckboxStateNeuralTreeFilterModeNeuralTreeFlatNode<T>NeuralTreeIndexEntry<T>NeuralTreeStateNeuralResolvedTreeState<T>NeuralTreeController<T>NeuralTreeOptionMappingCompatibility alias
TreeComponent remains deprecated for migration only. New application and generated code must import NeuralTree.
TREE
Design tokens
Every token below maps to a real Tree visual decision and inherits through Neutral and application themes.
Surface
--neural-tree-colorComponent foreground color.
--neural-tree-backgroundComponent background surface.
--neural-tree-borderComponent border shorthand.
--neural-tree-radiusComponent corner radius.
--neural-tree-shadowComponent box shadow.
--neural-tree-paddingComponent internal spacing.
--neural-tree-font-familyComponent font family.
Nodes and hierarchy
--neural-tree-node-heightNode block size.
--neural-tree-node-gapSpacing between node items.
--neural-tree-node-padding-blockLogical block-axis padding inside each Tree node.
--neural-tree-node-padding-inlineLogical inline-end padding inside each Tree node.
--neural-tree-node-radiusNode corner radius.
--neural-tree-node-background-hoverHovered node background surface.
--neural-tree-node-background-selectedSelected node background surface.
--neural-tree-node-background-partialBackground surface of a partially selected Tree node.
--neural-tree-node-color-selectedSelected node foreground color.
--neural-tree-node-icon-colorNode icon foreground color.
--neural-tree-node-icon-sizeNode icon width and height.
--neural-tree-match-colorMatch foreground color.
--neural-tree-disabled-opacityDisabled opacity.
--neural-tree-error-colorError severity foreground color.
--neural-tree-indentLogical inline indentation added for each nested Tree level.
Toggler and checkbox
--neural-tree-toggler-sizeToggler width and height.
--neural-tree-toggler-colorToggler foreground color.
--neural-tree-toggler-color-hoverHovered toggler foreground color.
--neural-tree-toggler-background-hoverHovered toggler background surface.
--neural-tree-checkbox-sizeCheckbox width and height.
--neural-tree-checkbox-radiusCheckbox corner radius.
--neural-tree-checkbox-colorCheckbox foreground color.
--neural-tree-checkbox-backgroundCheckbox background surface.
--neural-tree-checkbox-background-selectedSelected checkbox background surface.
--neural-tree-checkbox-border-colorCheckbox border color.
--neural-tree-checkbox-border-color-selectedSelected checkbox border color.
--neural-tree-content-gapSpacing between content items.
Compact density
--neural-tree-compact-node-heightCompact node block size.
--neural-tree-compact-indentNested Tree indentation used by compact mode.
--neural-tree-compact-toggler-sizeCompact toggler width and height.
--neural-tree-compact-content-gapSpacing between compact content items.