Tree

Explore hierarchical data with controlled expansion, selection and optional reordering.

Category: Data and hierarchy
Import: @neural-ui/core/tree
Selector: neu-tree

import { NeuTreeComponent } from '@neural-ui/core/tree';

Usage

nodes supplies flat records with stable keys and data; hierarchy describes roots and loaded/unloaded child relations. Apply expandedKeysChange.keys to expandedKeys and selectionChange.selection to selection. childrenRequest identifies an unloaded parent and request; the application loads children and replaces nodes/hierarchy. nodeMove is a proposal: update hierarchy to accept it. A Template receives node data, not the wrapper node.

Examples

Try this application-owned interaction. Its event handling and initial data are included in Code.

Search folders

Workspace

Design

Engineering

Try and configure

Change the public options, try the result and inspect the updated template. Code contains the complete executable implementation.

Search folders

Workspace

Design

Engineering

State and events

Accessibility and keyboard

Arrow keys traverse and expand/collapse nodes; Home/End reach the first/last visible node. Space changes selection. Reordering has keyboard alternatives when enabled.

Key	Action
`Tab`	Reach the tree and its enabled controls.
`ArrowDown / ArrowUp`	Focus the next or previous visible node.
`ArrowRight / ArrowLeft`	Expand, enter, collapse or leave a branch; horizontal direction follows RTL.
`Home`	Focus the first visible node.
`End`	Focus the last visible node.
`Enter`	Activate selection for the focused node when selection is enabled.
`Space`	Activate selection for the focused node when selection is enabled.

API

Inputs, models and Outputs are extracted from the installed Core package. Named public types link to their definitions. Templates below include executable examples.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Name	Type	Default	Template binding	Description
`ariaLabel`	`string`	`'Tree'`	`[ariaLabel]`	Accessible name of the tree.
`collapseLabel`	`string`	`'Collapse node'`	`[collapseLabel]`	Accessible label of the toggle in expanded mode.
`emptyLabel`	`string`	`'No nodes available'`	`[emptyLabel]`	Label for empty collection. Translate it for your application.
`expandedKeys`	`readonly K[]`	`[]`	`[expandedKeys]`	Applied keys of expanded branches. Expansion changes are proposed to the application.
`expandLabel`	`string`	`'Expand node'`	`[expandLabel]`	Accessible label of the toggle in collapsed mode.
`hierarchy`	`NeuTreeHierarchy<K>`	Required	`[hierarchy]`	Roots and child relations, with loaded/loading/error/unloaded state and revision identities.
`indentSize`	`number`	`18`	`[indentSize]`	Horizontal indentation per tree level in pixels.
`invalidTreeLabel`	`string`	`'Tree data is invalid'`	`[invalidTreeLabel]`	Accessible diagnostic text when hierarchy data is inconsistent.
`nodes`	`readonly NeuTreeNode<T, K>[]`	Required	`[nodes]`	Flat keyed node records. The separate hierarchy defines their parent/child relationships.
`reorderable`	`boolean`	`false`	`[reorderable]`	Enable tree node move proposals; the application still owns the hierarchy.
`retryLabel`	`string`	`'Retry loading'`	`[retryLabel]`	Visible or accessible label for retrying a failed load/upload.
`searchable`	`boolean`	`false`	`[searchable]`	Shows the built-in search field.
`searchLabel`	`string`	`'Search nodes'`	`[searchLabel]`	Accessible label or placeholder of the search field.
`selection`	`NeuTreeSelection<K>`	`{ mode: 'none' }`	`[selection]`	Applied discriminated selection state: none, single, multiple or checkbox.
`virtualization`	`NeuTreeVirtualization \| null`	`null`	`[virtualization]`	Virtual tree viewport configuration, or null for normal rendering.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Name	Payload	Template binding	Description
`childrenRequest`	`NeuTreeChildrenRequest<K>`	`(childrenRequest)="onChildrenRequest($event)"`	Requests children using parentKey, requestId and hierarchyRevision. Load records and update nodes/hierarchy.
`expandedKeysChange`	`NeuTreeExpandedKeysChange<K>`	`(expandedKeysChange)="onExpandedKeysChange($event)"`	Proposes the next branch keys. Update expandedKeys to accept a controlled change.
`nodeAction`	`NeuTreeNodeAction<K>`	`(nodeAction)="onNodeAction($event)"`	Emits the stable key of the activated node.
`nodeMove`	`NeuTreeNodeMove<K>`	`(nodeMove)="onNodeMove($event)"`	Proposes a move with source/target keys and position. Replace hierarchy to accept it.
`selectionChange`	`NeuTreeSelectionChange<K>`	`(selectionChange)="onSelectionChange($event)"`	Proposes selection together with the affected key and interaction source. Apply payload.selection to selection.

Templates

ng-content projects content into the component. TemplateRef inputs receive a template; ng-template directives identify templates with a typed context. A directive shared by an entrypoint is not necessarily a slot of this component.

Name	Mechanism	Contract
`NeuTreeNodeDirective`View example	Public template directive (entrypoint)	`ng-template[neuTreeNode]`

NeuTreeNodeDirectiveView example

Public template directive (entrypoint)

ng-template[neuTreeNode]

Declaration

import type { NeuTreeKey } from '@neural-ui/core/tree';

import { NeuTreeNodeDirective } from '@neural-ui/core/tree';

// Public declaration (reference only)
export declare class NeuTreeNodeDirective<T, K extends NeuTreeKey = string> {
}

Full context

import type { NeuTreeNodeTemplateContext } from '@neural-ui/core/tree';

import { NeuTreeNodeDirective } from '@neural-ui/core/tree';

// Public declaration (reference only)
readonly templateRef: TemplateRef<NeuTreeNodeTemplateContext<T, K>>;

Each example demonstrates a different template. Switch between Demo and Code to inspect its implementation, imports and state.

NeuTreeNodeDirective

NeuTreeNodeDirective

Search folders

WorkspaceLevel 1 · —

DesignLevel 2 · —

EngineeringLevel 2 · —

ArchiveLevel 1 · —

Events: 0

Public Types

Open a type to inspect its definition and interface fields.

NeuTreeChildrenRelationTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeChildrenRelation } from '@neural-ui/core/tree';

// Public declaration (reference only)
export type NeuTreeChildrenRelation<K extends NeuTreeKey> = {
    readonly parentKey: K;
    readonly state: 'unloaded';
} | {
    readonly parentKey: K;
    readonly state: 'loading';
    readonly requestId: number;
} | {
    readonly parentKey: K;
    readonly state: 'loaded';
    readonly keys: readonly K[];
} | {
    readonly parentKey: K;
    readonly state: 'error';
    readonly requestId?: number;
};

NeuTreeChildrenRequestTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeChildrenRequest } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeChildrenRequest<K extends NeuTreeKey> {
  readonly hierarchyRevision: number;
  readonly parentKey: K;
  readonly reason: 'expand' | 'retry';
  readonly requestId: number;
}

NeuTreeExpandedKeysChangeTypeScript

import type { NeuTreeInteractionSource } from '@neural-ui/core/tree';
import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeExpandedKeysChange } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeExpandedKeysChange<K extends NeuTreeKey> {
  readonly expanded: boolean;
  readonly key: K;
  readonly keys: readonly K[];
  readonly source: NeuTreeInteractionSource;
}

NeuTreeHierarchyTypeScript

import type { NeuTreeChildrenRelation } from '@neural-ui/core/tree';
import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeHierarchy } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeHierarchy<K extends NeuTreeKey> {
  readonly children: readonly NeuTreeChildrenRelation<K>[];
  readonly revision: number;
  readonly roots: readonly K[];
}

NeuTreeInteractionSourceTypeScript

import type { NeuTreeInteractionSource } from '@neural-ui/core/tree';

// Public declaration (reference only)
export type NeuTreeInteractionSource = 'pointer' | 'keyboard';

NeuTreeKeyTypeScript

NeuTreeMovePositionTypeScript

import type { NeuTreeMovePosition } from '@neural-ui/core/tree';

// Public declaration (reference only)
export type NeuTreeMovePosition = 'before' | 'inside' | 'after';

NeuTreeNodeTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeNode } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeNode<T, K extends NeuTreeKey = string> {
  readonly badge?: string;
  readonly data: T;
  readonly description?: string;
  readonly disabled?: boolean;
  readonly key: K;
  readonly label: string;
}

NeuTreeNodeActionTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeNodeAction } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeNodeAction<K extends NeuTreeKey> {
  readonly key: K;
}

NeuTreeNodeMoveTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';
import type { NeuTreeMovePosition } from '@neural-ui/core/tree';

import type { NeuTreeNodeMove } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeNodeMove<K extends NeuTreeKey> {
  readonly position: NeuTreeMovePosition;
  readonly sourceIndex: number;
  readonly sourceKey: K;
  readonly sourceParentKey: K | null;
  readonly targetIndex: number;
  readonly targetKey: K;
  readonly targetParentKey: K | null;
}

NeuTreeNodeTemplateContextTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeNodeTemplateContext } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeNodeTemplateContext<T, K extends NeuTreeKey = string> {
  readonly $implicit: T;
  readonly disabled: boolean;
  readonly expanded: boolean;
  readonly hasChildren: boolean;
  readonly key: K;
  readonly level: number;
  readonly loading: boolean;
  readonly partial: boolean;
  readonly selected: boolean;
}

NeuTreeSelectionTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeSelection } from '@neural-ui/core/tree';

// Public declaration (reference only)
export type NeuTreeSelection<K extends NeuTreeKey> = {
    readonly mode: 'none';
} | {
    readonly mode: 'single';
    readonly key: K | null;
} | {
    readonly mode: 'multiple';
    readonly keys: readonly K[];
} | {
    readonly mode: 'checkbox';
    readonly keys: readonly K[];
};

NeuTreeSelectionChangeTypeScript

import type { NeuTreeInteractionSource } from '@neural-ui/core/tree';
import type { NeuTreeKey } from '@neural-ui/core/tree';
import type { NeuTreeSelection } from '@neural-ui/core/tree';

import type { NeuTreeSelectionChange } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeSelectionChange<K extends NeuTreeKey> {
  readonly key: K;
  readonly selection: NeuTreeSelection<K>;
  readonly source: NeuTreeInteractionSource;
}

NeuTreeVirtualizationTypeScript

import type { NeuTreeVirtualization } from '@neural-ui/core/tree';

// Public declaration (reference only)
export interface NeuTreeVirtualization {
  readonly buffer?: number;
  readonly itemSize: number;
  readonly viewportHeight: number;
}

Styles and tokens

Use the supported public tokens listed below. Surrounding layout belongs to your application; validate the result in light and dark modes and narrow containers.

Specific tokens

This component uses shared theme tokens rather than dedicated component hooks.

Shared tokens used

Override these on a local wrapper to affect this example. An override on :root affects other components that use the same token.

Token	Purpose here	Other impact	Default / fallback
`--neu-border`	Normal control and cell borders	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.08)`
`--neu-focus-ring`	Normal keyboard-focus ring	Shared by other Core consumers; scope the override.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.15)`
`--neu-primary`	Brand color for active controls and emphasis	Shared by other Core consumers; scope the override.	`#007aff`
`--neu-primary-dark`	Dark brand shade; outline and ghost Button text in the light theme	Shared by other Core consumers; scope the override.	`#005fcc`
`--neu-primary-light`	Light brand shade; outline and ghost Button text in the dark theme	Shared by other Core consumers; scope the override.	`#339dff`
`--neu-surface`	Main field, header or control surface	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-surface-2`	Secondary surfaces and alternating rows	Shared by other Core consumers; scope the override.	`#f1f5f9`
`--neu-text`	Main text and inherited icon color	Shared by other Core consumers; scope the override.	`#0f172a`