TreeSelect | Neural UI v2

Uso

TreeSelect muestra la jerarquía dentro de su panel. El modo simple guarda el valor de un nodo; el modo múltiple guarda un array. La selección independent afecta al nodo elegido; propagated sigue las relaciones entre padres e hijos.

La expansión es controlada: enlaza expandedKeys y aplica expandedKeysChange. Para nodos lazy, childrenRequest solicita los hijos a la aplicación; no los descarga por sí mismo.

Signal Forms

Enlaza FormField al control que gestiona el valor y añade required al esquema del formulario. Selecciona un destino, sal del campo para marcarlo como visitado y restablécelo para comprobar el valor y la validación. La marca de obligatorio no valida por sí sola el formulario.

Guía de Signal Forms

Destino

Valor: — · Válido: false

Prueba y configura

Cambia las opciones e interactúa con el control. La vista previa, el valor de la aplicación y el template generado permanecen juntos. Un destino deshabilitado permite comprobar que no se pueden seleccionar opciones no disponibles.

Vista previa

Destino

Valor actual de la aplicación

Eventos: 0 ·

Opciones avanzadas · 6

Template generado: refleja las opciones anteriores. Los imports y el estado están en la pestaña Código.

<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"
  [clearLabel]="'Limpiar selección'"
  [emptyLabel]="'No hay destinos'"
  [label]="'Destino'"
  [placeholder]="'Elige un destino'"
  [searchPlaceholder]="'Buscar destinos'"
/>

Estado y datos de esta configuración

Estos valores corresponden a la vista previa actual. Los handlers, imports de Core y templates completos están en Código.

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

export const destinations = [
  {
    "value": "eu",
    "label": "Europa",
    "children": [
      {
        "value": "madrid",
        "label": "Madrid"
      },
      {
        "value": "lisbon",
        "label": "Lisboa"
      },
      {
        "value": "paris",
        "label": "París"
      },
      {
        "value": "rome",
        "label": "Roma",
        "disabled": true
      }
    ]
  },
  {
    "value": "americas",
    "label": "América",
    "children": [
      {
        "value": "bogota",
        "label": "Bogotá"
      },
      {
        "value": "lima",
        "label": "Lima"
      }
    ]
  }
];

export const destination = signal(null);

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

Inputs de datos, callbacks y configuración estructurada

Estos inputs requieren un modelo o función, no un checkbox. Modifica el campo del mismo nombre en el componente de Código y enlázalo al template; los datos que ya usa esta vista previa se muestran en el estado anterior.

mode · M

En Código: define mode con este tipo y utiliza [mode]="mode" (o mode() si es una signal).

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

En Código: define optionChildren con este tipo y utiliza [optionChildren]="optionChildren" (o optionChildren() si es una signal).

optionDisabled · NeuOptionDisabledAccessor<T> | null

En Código: define optionDisabled con este tipo y utiliza [optionDisabled]="optionDisabled" (o optionDisabled() si es una signal).

optionLabel · NeuOptionLabelAccessor<T> | null

En Código: define optionLabel con este tipo y utiliza [optionLabel]="optionLabel" (o optionLabel() si es una signal).

optionValue · NeuOptionValueAccessor<T, V> | null

En Código: define optionValue con este tipo y utiliza [optionValue]="optionValue" (o optionValue() si es una signal).

value · NeuSelectionValue<V, M>

En Código: define value con este tipo y utiliza [value]="value" (o value() si es una signal).

Valor y eventos

Usa una sola fuente de verdad: [(value)]="destination" o [value]="destination()" junto con (valueChange)="destination.set($event)". No combines las dos formas de enlace.

Los Inputs configuran el control. valueChange sincroniza su modelo; los demás Outputs comunican las acciones o fases documentadas. Las solicitudes de sugerencias, hijos o ventanas remotas requieren que la aplicación proporcione los datos.

Accesibilidad y teclado

Utiliza una etiqueta visible o un nombre accesible. Prueba la navegación por teclado, las opciones deshabilitadas, la selección y el cierre del panel. Los templates de opción deben conservar texto descriptivo y no introducir botones ni otro checkbox enfocable dentro de la opción.

Tecla	Acción
`Tab`	Mueve el foco hacia dentro o fuera del control.
`ArrowDown / ArrowUp`	Mueve la opción activa entre las opciones disponibles.
`Enter`	Activa la opción enfocada.
`Escape`	Cierra el panel sin seleccionar otra opción.

API

La referencia muestra los Inputs, modelos, Outputs y Templates públicos del paquete de Core fijado. Pulsa un tipo con nombre para abrir su definición. Cada Template aplicable tiene un ejemplo ejecutable y su código real.

Inputs

Configura el componente con [propiedad]="valor". Tu aplicación proporciona estos valores; el componente no debe reemplazar el estado que le pasas.

Nombre	Tipo	Por defecto	Uso en el template	Descripción
`clearable`	`boolean`	`false`	`[clearable]`	Muestra la acción de limpiar cuando hay un valor seleccionado.
`clearLabel`	`string`	`'Clear selection'`	`[clearLabel]`	Etiqueta de la acción que limpia la selección.
`disabled`	`boolean`	`false`	`[disabled]`	Deshabilita la interacción del usuario; las opciones deshabilitadas no se pueden seleccionar.
`emptyLabel`	`string`	`'No options found'`	`[emptyLabel]`	Mensaje que se muestra cuando no hay opciones disponibles.
`expandedKeys`	`readonly V[]`	`[]`	`[expandedKeys]`	Claves de nodos expandidos aplicadas. Actualiza este input para aceptar expandedKeysChange.
`label`	`string`	`''`	`[label]`	Etiqueta visible del campo o de la opción.
`mode`	`M`	`'single' as M`Valor derivado	`[mode]`	Modo de selección. El tipo del valor depende del modo elegido.
`nodes`	`readonly T[]`	`[]`	`[nodes]`	Nodos raíz. Las relaciones de hijos se leen mediante optionChildren.
`optionChildren`	`NeuOptionAccessor<T, readonly T[]> \| null`	`null`	`[optionChildren]`	Nombre de campo o función que lee los hijos de un nodo.
`optionDisabled`	`NeuOptionDisabledAccessor<T> \| null`	`null`	`[optionDisabled]`	Nombre de campo o función que indica si una opción está deshabilitada.
`optionLabel`	`NeuOptionLabelAccessor<T> \| null`	`null`	`[optionLabel]`	Nombre de campo o función que obtiene la etiqueta visible de la opción.
`optionValue`	`NeuOptionValueAccessor<T, V> \| null`	`null`	`[optionValue]`	Nombre de campo o función que obtiene el valor guardado de la opción.
`placeholder`	`string`	`'Select...'`	`[placeholder]`	Texto que se muestra cuando el campo no tiene un valor seleccionado.
`readonly`	`boolean`	`false`	`[readonly]`	Mantiene el valor visible sin permitir que el usuario lo cambie.
`searchable`	`boolean`	`true`	`[searchable]`	Muestra el campo de búsqueda de opciones integrado.
`searchPlaceholder`	`string`	`'Search...'`	`[searchPlaceholder]`	Placeholder del campo de búsqueda de opciones.
`selectionStrategy`	`NeuTreeSelectSelectionStrategy`	`'independent'`	`[selectionStrategy]`	Selección independiente de nodos o propagada entre padres e hijos.
`touched`	`boolean`	`false`	`[touched]`	Estado del formulario que indica que el control ha sido visitado.
`virtualizationOptions`	`Readonly<NeuTreeSelectVirtualizationOptions>`	`{}`	`[virtualizationOptions]`	Opciones del área visible del árbol: enabled, itemSize, viewportHeight y buffer.

Models

Un modelo admite [(propiedad)]="signal" o la pareja [propiedad] y (propiedadChange). Elige una de las dos formas, no ambas.

Nombre	Tipo	Por defecto	Uso en el template	Descripción
`value`	`NeuSelectionValue<V, M>`	`null as NeuSelectionValue<V, M>`Valor derivado	`[(value)]`	Modo simple: un valor o null. Modo múltiple: un array. La aplicación es propietaria del modelo enlazado.

Outputs

Escucha un evento con (evento)="handler($event)". La tabla indica qué datos recibe tu función y cómo utilizarlos.

Nombre	Valor emitido	Uso en el template	Descripción
`childrenRequest`	`NeuTreeSelectChildrenRequest<V>`	`(childrenRequest)="onChildrenRequest($event)"`	Solicita los hijos de un nodo lazy; actualiza sus datos cargados cuando estén disponibles.
`cleared`	`void`	`(cleared)="onCleared($event)"`	Se emite con la acción explícita de limpiar; valueChange comunica el valor resultante.
`closed`	`void`	`(closed)="onClosed($event)"`	Se emite después de cerrar el panel en el navegador.
`expandedKeysChange`	`readonly V[]`	`(expandedKeysChange)="onExpandedKeysChange($event)"`	Claves de expansión propuestas. Actualiza expandedKeys para aplicar el cambio.
`filter`	`{ query: string; }`	`(filter)="onFilter($event)"`	Consulta de búsqueda original modificada por el usuario.
`nodeCollapsed`	`T`	`(nodeCollapsed)="onNodeCollapsed($event)"`	Nodo contraído por una acción del usuario.
`nodeExpanded`	`T`	`(nodeExpanded)="onNodeExpanded($event)"`	Nodo expandido por una acción del usuario.
`opened`	`void`	`(opened)="onOpened($event)"`	Se emite después de abrir el panel en el navegador.
`rangeChange`	`NeuViewportRange`	`(rangeChange)="onRangeChange($event)"`	Rango visible actual del área virtual.
`touch`	`void`	`(touch)="onTouch($event)"`	Notifica al formulario que el control ha sido visitado; no es un cambio de valor.

Templates

ng-content proyecta contenido dentro del componente. Los inputs TemplateRef reciben un template; las directivas ng-template identifican templates con un contexto tipado. Una directiva compartida en el entrypoint no es necesariamente un slot de este componente.

Nombre	Mecanismo	Contrato
`NeuTreeSelectEmptyDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuTreeSelectEmpty]`
`NeuTreeSelectFooterDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuTreeSelectFooter]`
`NeuTreeSelectHeaderDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuTreeSelectHeader]`
`NeuTreeSelectNodeDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuTreeSelectNode]`
`NeuTreeSelectSelectedDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuTreeSelectSelected]`

Cada ejemplo muestra un template diferente. Alterna entre Demo y Código para consultar su implementación, imports y estado.

Template Empty

NeuTreeSelectEmptyDirective

Abre el control para ver el estado vacío.

Destino

Template Header

NeuTreeSelectHeaderDirective

Abre el control para ver el template personalizado.

Destino

Template Node

NeuTreeSelectNodeDirective

Abre el control para ver el template personalizado.

Destino

Template Selected

NeuTreeSelectSelectedDirective

Abre el control para ver el template personalizado.

Destino

Public Types

Abre un tipo para consultar su definición y los campos de sus interfaces.

NeuIndexRangeTypeScript

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

// Declaración pública (solo referencia)
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';

// Declaración pública (solo referencia)
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';

// Declaración pública (solo referencia)
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';

// Declaración pública (solo referencia)
export type NeuOptionLabelAccessor<T> = NeuOptionAccessor<T, string>;

NeuOptionPathTypeScript

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

// Declaración pública (solo referencia)
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';

// Declaración pública (solo referencia)
export type NeuOptionValueAccessor<T, V> = NeuOptionAccessor<T, V>;

NeuSelectionModeTypeScript

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

// Declaración pública (solo referencia)
export type NeuSelectionMode = 'single' | 'multiple';

NeuSelectionValueTypeScript

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

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

// Declaración pública (solo referencia)
export type NeuSelectionValue<V, M extends NeuSelectionMode> = M extends 'multiple' ? readonly V[] : V | null;

NeuTreeSelectChildrenRequestTypeScript

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

// Declaración pública (solo referencia)
export interface NeuTreeSelectChildrenRequest<K> {
  readonly parentKey: K;
  readonly queryRevision: number;
  readonly requestId: number;
}

NeuTreeSelectNodeTypeScript

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

// Declaración pública (solo referencia)
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';

// Declaración pública (solo referencia)
export interface NeuTreeSelectNodeTemplateContext<T = NeuTreeSelectNode> {
  $implicit: T;
  level: number;
  selected: boolean;
  toggle: () => void;
}

NeuTreeSelectSelectionStrategyTypeScript

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

// Declaración pública (solo referencia)
export type NeuTreeSelectSelectionStrategy = 'independent' | 'propagated';

NeuTreeSelectVirtualizationOptionsTypeScript

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

// Declaración pública (solo referencia)
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';

// Declaración pública (solo referencia)
export interface NeuViewportRange {
  readonly render: NeuIndexRange;
  readonly visible: NeuIndexRange;
}

Estilos y tokens

Carga los estilos de Core una sola vez. Utiliza los tokens públicos para personalizaciones locales o un preset para cambios de toda la aplicación. Conserva la legibilidad de etiquetas, foco, opciones seleccionadas y estados deshabilitados en modo claro y oscuro.

Tokens específicos

Este componente utiliza tokens compartidos del tema en lugar de tokens específicos.

Tokens compartidos utilizados

Sobrescríbelos en un contenedor local para afectar a este ejemplo. Una modificación en :root afecta a los demás componentes que utilizan el mismo token.

Token	Efecto aquí	Otros efectos	Valor / alternativa
`--neu-border`	Bordes normales de controles y celdas	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`rgba(15, 23, 42, 0.08)`
`--neu-focus-ring`	Anillo normal del foco de teclado	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.15)`
`--neu-primary`	Color de marca en controles activos y énfasis	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#007aff`
`--neu-radius`	Radio de las esquinas del control	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`8px`
`--neu-surface`	Superficie principal del campo, cabecera o control	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#ffffff`
`--neu-text`	Color del texto principal y de los iconos que lo heredan	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#0f172a`
`--neu-text-muted`	Etiquetas secundarias y contenido de ayuda	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#475569`
`--neu-shadow-lg`	Elevación de la superficie o capa	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`0 10px 30px rgba(15, 23, 42, 0.1), 0 4px 8px rgba(15, 23, 42, 0.04)`

Componentes relacionados

Elige el control según la interacción: una lista visible, un campo de búsqueda, una jerarquía o un conjunto de opciones exclusivas.

Inputs

Models

Outputs

Templates

Template Empty

Template Footer

Template Header

Template Node

Template Selected

Public Types

Tokens específicos

Tokens compartidos utilizados