Tree Table
Accessible controlled treegrid combining expandable hierarchy, sortable columns, selection, keyboard rows, and complete async states.
- Selector
- ui-tree-table
- Package
- @ngnova/ui/tree-table
Import
import { UiTreeTableComponent } from '@ngnova/ui/tree-table';Usage & variants
Live examples use the public ui-tree-table API, paired with the exact snippet a product team would paste into an Angular app.
Package hierarchy
Accessible controlled treegrid combining expandable hierarchy, sortable columns, selection, keyboard rows, and complete async states.
| Status | Owner | |
|---|---|---|
| Components | Ready | Design system |
| Button | Ready | Foundations |
| Table | Ready | Data |
| Utilities | Review | Platform |
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 hierarchical records that must also be compared across consistent columns.
Watch for
expanded, selected, and sort are controlled and require parent updates after change events.
Product recipes
Apply Tree Table in distinct, copyable product scenarios—not just an isolated component state.
Controlled package treegrid
Hierarchy and sorting requests remain parent-owned.
1 2 3 4 5 6 7 8 9 10 11
<ui-tree-table
[columns]="columns"
[nodes]="packages()"
[expanded]="expanded()"
(expandedChange)="expanded.set($event)"
[selected]="selected()"
(selectedChange)="selected.set($event)"
[sort]="sort()"
(sortChange)="loadSorted($event)"
caption="Package inventory"
/>Permission hierarchy
Show inherited access in a hierarchy while keeping permission values aligned in data columns.
1 2 3 4 5 6 7
<ui-tree-table
caption="Workspace permissions"
[columns]="permissionColumns"
[nodes]="permissionNodes"
[expandedKeys]="expandedPermissionKeys()"
(expandedKeysChange)="expandedPermissionKeys.set($event)"
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
columns [] readonly UiTreeTableColumn[] Column metadata with key, label, alignment ('start' by default; 'start' | 'center' | 'end' | 'left' | 'right'), and sorting.
nodes [] readonly UiTreeTableNode[] Nested rows with unique values, immutable data, disabled state, and children.
expanded [] readonly string[] Controlled expanded branch values.
selected null string | null Controlled selected row value.
sort null UiTreeTableSort | null Controlled column sort indicator.
caption 'Tree table' string Accessible name for the treegrid.
loading false boolean Shows and announces loading.
error false boolean Shows the alert state after loading.
selectable true boolean Enables controlled row selection.
loadingText 'Loading rows...' string Localized loading message.
errorText 'Unable to load rows.' string Localized failure message.
emptyText 'No rows found.' string Localized empty message.
expandAriaLabel 'Expand row' string Accessible expansion action label.
collapseAriaLabel 'Collapse row' string Accessible collapse action label.
| Name | Type | Default | Description |
|---|---|---|---|
columns | readonly UiTreeTableColumn[] | [] | Column metadata with key, label, alignment ('start' by default; 'start' | 'center' | 'end' | 'left' | 'right'), and sorting. |
nodes | readonly UiTreeTableNode[] | [] | Nested rows with unique values, immutable data, disabled state, and children. |
expanded | readonly string[] | [] | Controlled expanded branch values. |
selected | string | null | null | Controlled selected row value. |
sort | UiTreeTableSort | null | null | Controlled column sort indicator. |
caption | string | 'Tree table' | Accessible name for the treegrid. |
loading | boolean | false | Shows and announces loading. |
error | boolean | false | Shows the alert state after loading. |
selectable | boolean | true | Enables controlled row selection. |
loadingText | string | 'Loading rows...' | Localized loading message. |
errorText | string | 'Unable to load rows.' | Localized failure message. |
emptyText | string | 'No rows found.' | Localized empty message. |
expandAriaLabel | string | 'Expand row' | Accessible expansion action label. |
collapseAriaLabel | string | 'Collapse row' | Accessible collapse action label. |
Outputs
expandedChange OutputEmitterRef<readonly string[]> Emits a frozen next expansion collection.
selectedChange OutputEmitterRef<string | null> Emits the requested selected row value.
sortChange OutputEmitterRef<UiTreeTableSort> Emits the requested sort key and direction.
nodeActivated OutputEmitterRef<UiTreeTableNode> Emits an activated enabled hierarchical row.
| Name | Type | Description |
|---|---|---|
expandedChange | OutputEmitterRef<readonly string[]> | Emits a frozen next expansion collection. |
selectedChange | OutputEmitterRef<string | null> | Emits the requested selected row value. |
sortChange | OutputEmitterRef<UiTreeTableSort> | Emits the requested sort key and direction. |
nodeActivated | OutputEmitterRef<UiTreeTableNode> | Emits an activated enabled hierarchical row. |
Accessibility
- Uses native table structure enhanced with treegrid, row, columnheader, and gridcell roles.
- Hierarchical rows expose aria-level, aria-expanded, aria-selected, and aria-disabled.
- Sortable headers use native buttons and aria-sort; expansion controls have localized labels.
Keyboard behavior
- Arrow Up/Down, Home, and End move roving row focus.
- Arrow Right expands; Arrow Left collapses or returns to the parent row.
- Enter and Space activate the focused row; header and expansion buttons retain native behavior.
Testing guidance
- Assert treegrid semantics, hierarchy metadata, controlled expansion/selection/sort, parent focus, async states, disabled rows, localization, and UiTreeTableHarness behavior.