TreeSelect | Neural UI v2

Usage

TreeSelect keeps the hierarchy visible in its panel. Single mode stores one node value; multiple mode stores an array. Independent selection affects only the chosen node; propagated selection follows parent/child relationships.

Expansion is controlled: bind expandedKeys and apply expandedKeysChange. For lazy nodes, childrenRequest asks the application to supply child records; it does not fetch them itself.

Signal Forms

Bind FormField to the value-owning control and add required to the form schema. Select a destination, leave the field to mark it touched, and reset it to check both value and validation state. A required marker on its own does not validate your form.

Signal Forms guide

Destination

Value: — · Valid: false

Try and configure

Change the settings below and interact with the live control. The preview, current application value and generated template stay together. A disabled destination lets you check that unavailable choices cannot be selected.

Live preview

Destination

Current application value

Events: 0 ·

Advanced options · 6

Generated template: reflects the settings above. Imports and state are in the Code tab.

<neu-tree-select
  (opened)="record('opened', $event)"
  (closed)="record('closed', $event)"
  (nodeExpanded)="record('nodeExpanded', $event)"
  (nodeCollapsed)="record('nodeCollapsed', $event)"
  (childrenRequest)="loadChildren($event)"
  (rangeChange)="record('rangeChange', $event)"
  (filter)="record('filter', $event)"
  (cleared)="record('cleared', $event)"
  (touch)="record('touch', $event)"
  (valueChange)="record('valueChange', $event)"
  [nodes]="destinations"
  [(value)]="destination"
  [expandedKeys]="expandedKeys()"
  (expandedKeysChange)="expandedKeys.set($event)"
  [clearable]="true"
  [emptyLabel]="'No destinations'"
  [label]="'Destination'"
  [placeholder]="'Choose a destination'"
  [searchPlaceholder]="'Search destinations'"
/>

State and data for this configuration

These values match the current preview. Complete handlers, Core imports and templates are in Source.

import { signal } from '@angular/core';

export const destinations = [
  {
    "value": "eu",
    "label": "Europe",
    "children": [
      {
        "value": "madrid",
        "label": "Madrid"
      },
      {
        "value": "lisbon",
        "label": "Lisbon"
      },
      {
        "value": "paris",
        "label": "Paris"
      },
      {
        "value": "rome",
        "label": "Rome",
        "disabled": true
      }
    ]
  },
  {
    "value": "americas",
    "label": "Americas",
    "children": [
      {
        "value": "bogota",
        "label": "Bogotá"
      },
      {
        "value": "lima",
        "label": "Lima"
      }
    ]
  }
];

export const destination = signal(null);

export const expandedKeys = signal([
  "eu"
]);

Data, callback and structured configuration inputs

These inputs require a model or function, not a checkbox. Edit the same-named field in the Source component and bind it in the template; data already used by this preview appears in the state above.

mode · M

In Source: define mode with this type and use [mode]="mode" (or mode() for a signal).

optionChildren · NeuOptionAccessor<T, readonly T[]> | null

In Source: define optionChildren with this type and use [optionChildren]="optionChildren" (or optionChildren() for a signal).

optionDisabled · NeuOptionDisabledAccessor<T> | null

In Source: define optionDisabled with this type and use [optionDisabled]="optionDisabled" (or optionDisabled() for a signal).

optionLabel · NeuOptionLabelAccessor<T> | null

In Source: define optionLabel with this type and use [optionLabel]="optionLabel" (or optionLabel() for a signal).

optionValue · NeuOptionValueAccessor<T, V> | null

In Source: define optionValue with this type and use [optionValue]="optionValue" (or optionValue() for a signal).

value · NeuSelectionValue<V, M>

In Source: define value with this type and use [value]="value" (or value() for a signal).

Value and events

Use one source of truth: [(value)]="destination" or [value]="destination()" with (valueChange)="destination.set($event)". Do not bind both forms at once.

Inputs configure the control. valueChange synchronizes its model; the other Outputs report their documented actions or lifecycle. Requests for suggestions, children or remote windows require the application to supply data.

Accessibility and keyboard

Use a visible label or an accessible name. Test keyboard navigation, disabled options, selection and closing the panel. Custom option templates should keep descriptive text and must not introduce a nested button or another focusable checkbox inside the option.

Key	Action
`Tab`	Moves focus into or out of the control.
`ArrowDown / ArrowUp`	Moves the active option through available options.
`Enter`	Activates the focused option.
`Escape`	Closes the panel without selecting another option.

API

The reference lists the public Inputs, models, Outputs and Templates from the pinned Core package. Click a named type to open its definition. Each applicable Template has an executable example and its actual source.

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
`clearable`	`boolean`	`false`	`[clearable]`	Shows a clear action when a value is selected.
`clearLabel`	`string`	`'Clear selection'`	`[clearLabel]`	Label for the clear-selection action.
`disabled`	`boolean`	`false`	`[disabled]`	Disables user interaction; disabled options cannot be selected.
`emptyLabel`	`string`	`'No options found'`	`[emptyLabel]`	Message displayed when there are no available options.
`expandedKeys`	`readonly V[]`	`[]`	`[expandedKeys]`	Applied node expansion keys. Accept expandedKeysChange by updating this input.
`label`	`string`	`''`	`[label]`	Visible field or option label.
`mode`	`M`	`'single' as M`Derived default	`[mode]`	Selection mode. The accepted value shape follows the chosen mode.
`nodes`	`readonly T[]`	`[]`	`[nodes]`	Root node records. Child relationships come from optionChildren.
`optionChildren`	`NeuOptionAccessor<T, readonly T[]> \| null`	`null`	`[optionChildren]`	Field name or function that reads a node's children.
`optionDisabled`	`NeuOptionDisabledAccessor<T> \| null`	`null`	`[optionDisabled]`	Field name or function that marks an option as disabled.
`optionLabel`	`NeuOptionLabelAccessor<T> \| null`	`null`	`[optionLabel]`	Field name or function used to obtain the visible option label.
`optionValue`	`NeuOptionValueAccessor<T, V> \| null`	`null`	`[optionValue]`	Field name or function used to obtain the stored option value.
`placeholder`	`string`	`'Select...'`	`[placeholder]`	Text shown when the field has no selected value.
`readonly`	`boolean`	`false`	`[readonly]`	Keeps the value readable without allowing the user to change it.
`searchable`	`boolean`	`true`	`[searchable]`	Displays the built-in option search field.
`searchPlaceholder`	`string`	`'Search...'`	`[searchPlaceholder]`	Placeholder for the option search field.
`selectionStrategy`	`NeuTreeSelectSelectionStrategy`	`'independent'`	`[selectionStrategy]`	Independent node selection or propagation through parent/child relationships.
`touched`	`boolean`	`false`	`[touched]`	Form state indicating that the control has been visited.
`virtualizationOptions`	`Readonly<NeuTreeSelectVirtualizationOptions>`	`{}`	`[virtualizationOptions]`	Tree viewport settings: enabled, itemSize, viewportHeight and buffer.

Models

A model supports [(property)]="signal" or the [property] and (propertyChange) pair. Choose one form, not both.

Name	Type	Default	Template binding	Description
`value`	`NeuSelectionValue<V, M>`	`null as NeuSelectionValue<V, M>`Derived default	`[(value)]`	Single mode: one value or null. Multiple mode: an array. The application owns the bound model.

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`	`NeuTreeSelectChildrenRequest<V>`	`(childrenRequest)="onChildrenRequest($event)"`	Requests children for a lazy node; update the loaded node data when ready.
`cleared`	`void`	`(cleared)="onCleared($event)"`	Emitted for the explicit clear action; valueChange carries the resulting value.
`closed`	`void`	`(closed)="onClosed($event)"`	Emitted after the browser panel closes.
`expandedKeysChange`	`readonly V[]`	`(expandedKeysChange)="onExpandedKeysChange($event)"`	Proposed expansion keys. Update expandedKeys to apply the change.
`filter`	`{ query: string; }`	`(filter)="onFilter($event)"`	Changed raw search query from user input.
`nodeCollapsed`	`T`	`(nodeCollapsed)="onNodeCollapsed($event)"`	Node collapsed by a user action.
`nodeExpanded`	`T`	`(nodeExpanded)="onNodeExpanded($event)"`	Node expanded by a user action.
`opened`	`void`	`(opened)="onOpened($event)"`	Emitted after the browser panel opens.
`rangeChange`	`NeuViewportRange`	`(rangeChange)="onRangeChange($event)"`	Current visible virtual viewport range.
`touch`	`void`	`(touch)="onTouch($event)"`	Notifies the form that the control has been touched; not a value change.

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
`NeuTreeSelectEmptyDirective`View example	Public template directive (entrypoint)	`ng-template[neuTreeSelectEmpty]`
`NeuTreeSelectFooterDirective`View example	Public template directive (entrypoint)	`ng-template[neuTreeSelectFooter]`
`NeuTreeSelectHeaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuTreeSelectHeader]`
`NeuTreeSelectNodeDirective`View example	Public template directive (entrypoint)	`ng-template[neuTreeSelectNode]`
`NeuTreeSelectSelectedDirective`View example	Public template directive (entrypoint)	`ng-template[neuTreeSelectSelected]`

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

Empty template

NeuTreeSelectEmptyDirective

Open the control to see the empty state.

Destination

Header template

NeuTreeSelectHeaderDirective

Open the control to see the custom template.

Destination

Node template

NeuTreeSelectNodeDirective

Open the control to see the custom template.

Destination

Selected template

NeuTreeSelectSelectedDirective

Open the control to see the custom template.

Destination

Public Types

Open a type to inspect its definition and interface fields.

NeuIndexRangeTypeScript

import type { NeuIndexRange } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export interface NeuIndexRange {
  readonly end: number;
  readonly start: number;
}

NeuOptionAccessorTypeScript

import type { NeuOptionPath } from '@neural-ui/core/option-api';

import type { NeuOptionAccessor } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionAccessor<T, R = unknown> = Exclude<keyof T, string> | NeuOptionPath<T> | ((option: T) => R);

NeuOptionDisabledAccessorTypeScript

import type { NeuOptionAccessor } from '@neural-ui/core/option-api';

import type { NeuOptionDisabledAccessor } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionDisabledAccessor<T> = NeuOptionAccessor<T, boolean>;

NeuOptionLabelAccessorTypeScript

import type { NeuOptionAccessor } from '@neural-ui/core/option-api';

import type { NeuOptionLabelAccessor } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionLabelAccessor<T> = NeuOptionAccessor<T, string>;

NeuOptionPathTypeScript

import type { NeuOptionPath } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionPath<T> = Extract<keyof T, string> | `${Extract<keyof T, string>}.${string}`;

NeuOptionValueAccessorTypeScript

import type { NeuOptionAccessor } from '@neural-ui/core/option-api';

import type { NeuOptionValueAccessor } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionValueAccessor<T, V> = NeuOptionAccessor<T, V>;

NeuSelectionModeTypeScript

NeuSelectionValueTypeScript

import type { NeuSelectionMode } from '@neural-ui/core/option-api';

import type { NeuSelectionValue } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuSelectionValue<V, M extends NeuSelectionMode> = M extends 'multiple' ? readonly V[] : V | null;

NeuTreeSelectChildrenRequestTypeScript

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

// Public declaration (reference only)
export interface NeuTreeSelectChildrenRequest<K> {
  readonly parentKey: K;
  readonly queryRevision: number;
  readonly requestId: number;
}

NeuTreeSelectNodeTypeScript

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

// Public declaration (reference only)
export interface NeuTreeSelectNode {
  children?: NeuTreeSelectNode[];
  data?: unknown;
  disabled?: boolean;
  label: string;
  lazy?: boolean;
  value: string;
}

NeuTreeSelectNodeTemplateContextTypeScript

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

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

// Public declaration (reference only)
export interface NeuTreeSelectNodeTemplateContext<T = NeuTreeSelectNode> {
  $implicit: T;
  level: number;
  selected: boolean;
  toggle: () => void;
}

NeuTreeSelectSelectionStrategyTypeScript

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

// Public declaration (reference only)
export type NeuTreeSelectSelectionStrategy = 'independent' | 'propagated';

NeuTreeSelectVirtualizationOptionsTypeScript

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

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

NeuViewportRangeTypeScript

import type { NeuIndexRange } from '@neural-ui/core/option-api';

import type { NeuViewportRange } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export interface NeuViewportRange {
  readonly render: NeuIndexRange;
  readonly visible: NeuIndexRange;
}

Styles and tokens

Load Core styles once. Use the public tokens below for local customization or a preset for application-wide changes. Keep labels, focus, selected options and disabled states readable in both light and dark themes.

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-radius`	Control corner radius	Shared by other Core consumers; scope the override.	`8px`
`--neu-surface`	Main field, header or control surface	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-text`	Main text and inherited icon color	Shared by other Core consumers; scope the override.	`#0f172a`
`--neu-text-muted`	Secondary labels and supporting content	Shared by other Core consumers; scope the override.	`#475569`
`--neu-shadow-lg`	Surface or overlay elevation	Shared by other Core consumers; scope the override.	`0 10px 30px rgba(15, 23, 42, 0.1), 0 4px 8px rgba(15, 23, 42, 0.04)`

Related components

Choose the control according to the interaction: a visible list, a search field, a hierarchy or an exclusive set of options.

Inputs

Models

Outputs

Templates

Empty template

Footer template

Header template

Node template

Selected template

Public Types

Specific tokens

Shared tokens used