Angular primitives
The same primitives and hooks for Angular 22, from @fragiola/tree-angular, and how each React prop maps onto directives, inputs, outputs and templates.
@fragiola/tree-angular has every primitive of the React package, as a standalone attribute
directive on an element you write, and every hook as an injection function, over the same core
(re-exported whole). The behaviour, the ARIA, the data-* attributes, data-tree-part and
data-tree-path of every element are the same: the React pages of this reference describe each
part, and this page says how its React API is written in Angular.
import { Component } from "@angular/core";
import {
createTreeModel,
injectTree,
injectTreeState,
TREE,
type TreeJson,
} from "@fragiola/tree-angular";
// each feature from its own entry (an Angular secondary entry point)
import { selection } from "@fragiola/tree-angular/selection";
import {
injectTreeVirtualWindow,
TreeVirtualItemsDirective,
virtualization,
} from "@fragiola/tree-angular/virtualization";
@Component({ imports: [TREE], template: `…` })
export class Files {}TREE lists every directive of the main entry, for a standalone component's imports; a
feature's directives come with its entry (TreeVirtualItemsDirective, in imports next to
TREE), so a tree that does not import the feature does not ship them
(Features). The package is standalone
only (no NgModule) and built on signals and host bindings: it needs no zone.js (zoneless is
Angular's default). It needs @angular/core ^22.
The element is yours
A directive goes on the element you choose: <li [treeItem]="item" class="…">. It adds the
part's role, its ARIA, its data-* state, its listeners and its structural inline style
(--tree-depth, the drop indicator's geometry, display: none on what is not shown); your
class, your other attributes and your listeners stay as they are (the directive's own listener
runs first). The structural style keys win over a static style you write on the element; a
[style.x] binding of yours on a structural key would fight the part, so leave those keys to it.
Each directive's state is a signal, through exportAs:
<div [treeItem]="item" #node="treeItem">
<div treeItemContent [class.font-semibold]="node.state().level === 1">{{ item.label }}</div>
</div>The recursion: one template
React's children functions are one <ng-template treeItems let-item>. Directly inside
[treeRoot], it renders with each root item; a [treeGroup] with no template of its own renders
each of its children with that same template, so one template renders every level. A group may
hold an <ng-template treeItems> of its own, for children that look different.
<div [treeRoot]="model" aria-label="Files">
<ng-template [treeItems]="model" let-item>
<div [treeItem]="item">
<div treeItemContent>
<span treeToggle>▸</span>
{{ item.label }}
</div>
<div treeGroup></div>
</div>
</ng-template>
</div>| template directive | inside | context (let-…) |
|---|---|---|
TreeItemsDirective (ng-template[treeItems]) | [treeRoot], or a [treeGroup] | $implicit and item: the item, a TreeItemsContext<T> |
TreeVirtualItemsDirective (ng-template[treeVirtualItems], from @fragiola/tree-angular/virtualization) | a [treeRoot] whose model has the virtualization() feature | $implicit and item: the item, and row, its VirtualRow: a TreeVirtualItemsContext<T> |
Typing by your registry. A template cannot pass a type argument. Give the template directive
the model or the document instead ([treeItems]="model", [treeItems]="json"; TypedBy<T> is
what it takes): its item is then typed by the registry, and item.data narrows on item.kind
under strictTemplates. A bare treeItems types it by AnyTypes. [treeRoot]="model" types the
root (TreeRootDirective<T>).
How React's props map
| React | Angular |
|---|---|
<Tree.Root model={model}> | <div [treeRoot]="model">; <Tree.Root defaultTree={json}> is <div treeRoot [defaultTree]="json"> |
<Tree.Item item={item}> | <div [treeItem]="item">: the directive's main input is its item |
render={<li />} | the element you put the directive on |
render={(props, state) => …} | the directive's state() through exportAs (#node="treeItem") |
className, style | your class and style, untouched; structural keys win. className={(state) => …} is a [class.x] binding on the state, or a data-* selector |
onClick, onKeyDown, … | your listeners ((click), (keydown)), run after the part's own |
ref | the element is yours: a template reference or viewChild |
children functions (Tree.Items, Tree.Group) | <ng-template treeItems let-item>, and [treeGroup] with no template of its own |
expandedItemIds + onExpandedItemIdsChange | [(expandedItemIds)] (or [expandedItemIds] with (expandedItemIdsChange)) |
selectedItemIds + onSelectedItemIdsChange | [(selectedItemIds)] |
checkedItemIds + onCheckedItemIdsChange (checkboxes()) | [(checkedItemIds)]: an input of every root, ignored with a warning without the feature |
useTreeItemRename(item, { onRenameError }) (@fragiola/tree-react/rename) | input[treeItemRename] (TreeItemRenameDirective, from @fragiola/tree-angular/rename, in your component's imports) on your own input inside an item, rendered with @if, and its output (renameError) |
treeRef={tree} | #tree="treeRoot" in the template, viewChild(TreeRootDirective) in the class: model() and engine |
defaultTree, expandOnClick, keyMap, … | the same inputs ([defaultTree], expandOnClick, [keyMap]); a boolean input takes a bare attribute (expandOnClick) |
<Tree.Items<Types>> and the other type arguments | [treeItems]="model" (or the document) |
a part that renders nothing (Tree.Group while collapsed, DropIndicator with no target) | the element stays, hidden (display: none); a collapsed group is also empty |
A controlled list the app does not update reverts the change: a one-way [expandedItemIds]
whose output is not handled keeps the tree on the input.
Directives
| directive | selector | exportAs | inputs | outputs |
|---|---|---|---|---|
TreeRootDirective | [treeRoot] | treeRoot | treeRoot (the model), defaultTree, features, expandedItemIds, selectedItemIds, checkedItemIds, loadChildren, announce, keyMap, expandOnClick | expandedItemIdsChange, selectedItemIdsChange, checkedItemIdsChange |
TreeItemsDirective | ng-template[treeItems] | treeItems | treeItems (typing: the model or the document) | none |
TreeVirtualItemsDirective | ng-template[treeVirtualItems] | treeVirtualItems | treeVirtualItems (typing: the model or the document) | none |
TreeItemDirective | [treeItem] | treeItem | treeItem (the item) | none |
TreeItemContentDirective | [treeItemContent] | treeItemContent | none | none |
TreeGroupDirective | [treeGroup] | treeGroup | keepMounted | none |
TreeToggleDirective | [treeToggle] | treeToggle | none | none |
TreeLiveRegionDirective | [treeLiveRegion] | treeLiveRegion | none | none |
TREE holds them all. A feature's directive comes from its entry, in your component's imports:
| directive | selector | exportAs | inputs | outputs |
|---|---|---|---|---|
TreeItemRenameDirective (@fragiola/tree-angular/rename) | input[treeItemRename] | treeItemRename | none | renameError |
TreeDropIndicatorDirective (@fragiola/tree-angular/drag-and-drop, and /foreign-drop; DropIndicatorState) | [treeDropIndicator] | treeDropIndicator | none | none |
The classes end in Directive because the core, re-exported, already has a TreeItem type.
Another model, or another engine option (keyMap, expandOnClick, …), makes another engine.
Create the model once, in a field (readonly model = createTreeModel<Types>(json)).
Through exportAs, every directive has state(): RootState on the root (with model(),
engine and the root's context), TreeItemState on the parts of an item,
TreeItemRenameState (renaming, invalid, error) on [treeItemRename], DropIndicatorState | null on the drop indicator and
LiveRegionState (announcement) on the live region. A group also has children(), the items it
renders. Drop the indicator from the DOM while there is no drag with
@if (tree.state().dragging) around it.
Injection functions
The hooks of the React reference, as injection functions. Call them in an injection context (a field initializer or a constructor) of a component inside the root.
| function | returns |
|---|---|
injectTree<T, F>() | { model, engine }, an InjectTreeResult<T, F> (F: the model's features, which type its commands and keys): model is a signal (model()), engine the tree on screen |
injectTreeItem<T>() | { item, state }, an InjectTreeItemResult<T>: the enclosing [treeItem]'s item and TreeItemState, as signals |
injectTreeVirtualWindow() (from @fragiola/tree-angular/virtualization) | a signal of the root's VirtualWindow (the rows a virtualized tree renders), null before the root created its engine and without the virtualization() feature |
injectTreeState(selector, options?) | a signal of the selection, changed only when isEqual says it changed (InjectTreeStateOptions: model, a model or a signal of one, and isEqual); it selects again when a signal the selector reads changes |
A tree ref is a template reference (#tree="treeRoot") or viewChild(TreeRootDirective): its
model() and its engine reach the tree from outside it. TreeRootDirective<T, F> is typed by the
model it is given; viewChild.required<TreeRootDirective<Types, typeof features>>(TreeRootDirective)
types it from outside. A feature's controlled list ([(selectedItemIds)]) is an input of every root
(an input is declared on the class): without its feature it is ignored, with a warning.
A server render outputs the tree's markup, never subscribes to the model and never runs a command
on it: the engine starts after the root's first render in the browser (afterNextRender).
Types
RootState, TreeItemState, TreeItemRenameState, DropIndicatorState, LiveRegionState,
InjectTreeResult, InjectTreeItemResult, InjectTreeStateOptions, and:
| type | description |
|---|---|
TreeItemsContext<T> | the context of <ng-template treeItems>: $implicit and item |
TreeVirtualItemsContext<T> | the context of <ng-template treeVirtualItems>: $implicit, item and row (from @fragiola/tree-angular/virtualization) |
TypedBy<T> | what [treeItems] takes to type its template: a model, a document, or nothing |
Examples
Every example of the gallery exists in Angular, with the same behaviour: pick Angular in the
framework switch to see its code. The file explorer shows the recursion
with one template, controlled the two-way lists and
undo and redo an app store read through a signal kept in step with its
subscribe.