Tree
Accessible controlled hierarchy with flattened visible nodes, roving focus, complete arrow-key navigation, and typeahead.
- Selector
- ui-tree
- Package
- @ngnova/ui/tree
Import
import { UiTreeComponent } from '@ngnova/ui/tree';Usage & variants
Live examples use the public ui-tree API, paired with the exact snippet a product team would paste into an Angular app.
Documentation hierarchy
Accessible controlled hierarchy with flattened visible nodes, roving focus, complete arrow-key navigation, and typeahead.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for file explorers, nested navigation, taxonomies, and other parent/child structures.
Watch for
expanded and selected are controlled; update them after their change events.
Product recipes
Apply Tree in distinct, copyable product scenarios—not just an isolated component state.
Controlled project tree
Expansion and selection remain parent-owned and immutable.
1 2 3 4 5 6 7 8 9
<ui-tree
[nodes]="projectNodes"
[expanded]="expanded()"
(expandedChange)="expanded.set($event)"
[selected]="selected()"
(selectedChange)="selected.set($event)"
(nodeActivated)="openNode($event)"
ariaLabel="Project files"
/>Workspace navigation
Use selection and expansion together for a navigable hierarchy whose state remains parent-owned.
1 2 3 4 5 6 7 8
<ui-tree
ariaLabel="Workspace navigation"
[nodes]="workspaceNodes"
[selectedKey]="selectedWorkspaceKey()"
[expandedKeys]="expandedWorkspaceKeys()"
(selectedKeyChange)="openWorkspaceItem($event)"
(expandedKeysChange)="expandedWorkspaceKeys.set($event)"
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
nodes [] readonly UiTreeNode[] Nested nodes with unique values, labels, descriptions, disabled state, and children.
expanded [] readonly string[] Controlled values of expanded branch nodes.
selected null string | null Controlled selected node value.
ariaLabel 'Tree' string Accessible name for the tree.
emptyText 'No items.' string Localized status shown when the hierarchy is empty.
selectable true boolean Enables single-selection semantics and selectedChange.
expandOnActivate true boolean Toggles branches when activated by click, Enter, or Space.
| Name | Type | Default | Description |
|---|---|---|---|
nodes | readonly UiTreeNode[] | [] | Nested nodes with unique values, labels, descriptions, disabled state, and children. |
expanded | readonly string[] | [] | Controlled values of expanded branch nodes. |
selected | string | null | null | Controlled selected node value. |
ariaLabel | string | 'Tree' | Accessible name for the tree. |
emptyText | string | 'No items.' | Localized status shown when the hierarchy is empty. |
selectable | boolean | true | Enables single-selection semantics and selectedChange. |
expandOnActivate | boolean | true | Toggles branches when activated by click, Enter, or Space. |
Outputs
expandedChange OutputEmitterRef<readonly string[]> Emits a frozen next expanded-value collection.
selectedChange OutputEmitterRef<string | null> Emits the requested single selected value.
nodeActivated OutputEmitterRef<UiTreeNode> Emits the activated enabled node for navigation or commands.
| Name | Type | Description |
|---|---|---|
expandedChange | OutputEmitterRef<readonly string[]> | Emits a frozen next expanded-value collection. |
selectedChange | OutputEmitterRef<string | null> | Emits the requested single selected value. |
nodeActivated | OutputEmitterRef<UiTreeNode> | Emits the activated enabled node for navigation or commands. |
Accessibility
- Uses tree/treeitem roles with aria-level, aria-posinset, aria-setsize, aria-expanded, aria-selected, and aria-disabled.
- Provide a specific ariaLabel and unique stable node values.
- Disabled nodes remain discoverable but cannot expand, select, or activate.
Keyboard behavior
- Arrow Down/Up moves visible focus; Home/End moves to the first/last visible node.
- Arrow Right expands a closed branch or enters its first child; Arrow Left collapses or returns to the parent.
- Enter and Space activate; a printable character moves to the next visible label with that initial.
Testing guidance
- Assert hierarchy metadata, controlled expansion/selection, disabled behavior, complete keyboard navigation, typeahead, focus visibility, localization, and UiTreeHarness interaction.