Component v1.1.0 Navigation/Data

Tree

Accessible controlled hierarchy with flattened visible nodes, roving focus, complete arrow-key navigation, and typeahead.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-tree
Package
@ngnova/ui/tree

Import

Standalone Tailwind v4
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.

API Reference

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.

Angular template ui-tree-recipe.example.html
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.

Angular template ui-tree-recipe.example.html
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.

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.

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.