Listbox | Neural UI v2

Uso

Elige Listbox cuando las opciones deben permanecer visibles en lugar de abrir un panel. Los modos simple y múltiple utilizan el mismo contrato de valor que Select.

En el modo múltiple, los indicadores de checkbox hacen explícita la selección. Seleccionar todo afecta a las opciones visibles habilitadas. El scroll virtual limita el área renderizada en colecciones grandes.

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 ·

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

<neu-listbox
  (optionActivated)="record('optionActivated', $event)"
  (filterChange)="onFilterChange($event)"
  (dataRequest)="record('dataRequest', $event)"
  (rangeChange)="record('rangeChange', $event)"
  (focusEntered)="record('focusEntered', $event)"
  (focusLeft)="record('focusLeft', $event)"
  (touch)="record('touch', $event)"
  (drop)="record('drop', $event)"
  (valueChange)="record('valueChange', $event)"
  [options]="destinations"
  [(value)]="destination"
  [searchable]="true"
  [ariaFilterLabel]="'Buscar destinos'"
  [checkbox]="true"
  [emptyLabel]="'No hay destinos'"
  [fluid]="true"
  [label]="'Destino'"
  [noResultsMessage]="'Sin coincidencias'"
  [searchPlaceholder]="'Buscar'"
  [toggleAllLabel]="'Seleccionar todas las opciones visibles'"
/>

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": "madrid",
    "label": "Madrid"
  },
  {
    "value": "lisbon",
    "label": "Lisboa"
  },
  {
    "value": "paris",
    "label": "París"
  },
  {
    "value": "rome",
    "label": "Roma",
    "disabled": true
  }
];

export const destination = signal(null);

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.

compareWith · (left: V, right: V) => boolean

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

errors · readonly ValidationError.WithOptionalFieldTree[]

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

filterConfig · Readonly<NeuOptionFilterConfig<T>>

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

groupConfig · NeuOptionGroupConfig<T, G> | null

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

groups · readonly G[]

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

listStyle · Record<string, string | number> | null

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

mode · M

En Código: define mode con este tipo y utiliza [mode]="mode" (o mode() 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 · (option: T) => V

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.

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
`ariaDescribedBy`	`string \| null`	`null`	`[ariaDescribedBy]`	IDs de los elementos que describen el control, separados por espacios.
`ariaFilterLabel`	`string`	`'Filter options'`	`[ariaFilterLabel]`	Nombre accesible del campo de búsqueda de opciones.
`ariaLabel`	`string`	`'Options'`	`[ariaLabel]`	Nombre accesible cuando no hay una etiqueta visible.
`ariaLabelledBy`	`string \| null`	`null`	`[ariaLabelledBy]`	ID del elemento que proporciona el nombre accesible.
`autoOptionFocus`	`boolean`	`true`	`[autoOptionFocus]`	Activa una opción disponible al abrir la lista.
`checkbox`	`boolean`	`false`	`[checkbox]`	Muestra indicadores de checkbox en la selección múltiple.
`checkmark`	`boolean`	`false`	`[checkmark]`	Muestra una marca junto a las opciones seleccionadas.
`compareWith`	`(left: V, right: V) => boolean`	`Object.is`Valor derivado	`[compareWith]`	Función para comparar valores seleccionados; utiliza una identidad de dominio estable.
`dataFirst`	`number`	`0`	`[dataFirst]`	Índice lógico de la primera opción cargada en una ventana remota.
`dirty`	`boolean`	`false`	`[dirty]`	Estado del formulario que indica que el usuario ha cambiado el valor.
`disabled`	`boolean`	`false`	`[disabled]`	Deshabilita la interacción del usuario; las opciones deshabilitadas no se pueden seleccionar.
`dragdrop`	`boolean`	`false`	`[dragdrop]`	Permite arrastrar y soltar entre listboxes compatibles.
`emptyLabel`	`string`	`'No options found'`	`[emptyLabel]`	Mensaje que se muestra cuando no hay opciones disponibles.
`errors`	`readonly ValidationError.WithOptionalFieldTree[]`	`[]`	`[errors]`	Errores de validación proporcionados por el formulario o la aplicación.
`filterConfig`	`Readonly<NeuOptionFilterConfig<T>>`	`{}`	`[filterConfig]`	Campos, modo de comparación, idioma y estrategia de filtrado local o remoto.
`filterValue`	`string \| null`	`null`	`[filterValue]`	Consulta de búsqueda aplicada. Escucha filterChange si la controla la aplicación.
`fluid`	`boolean`	`false`	`[fluid]`	Hace que el control ocupe el ancho de su contenedor.
`focusOnHover`	`boolean`	`true`	`[focusOnHover]`	Cambia la opción activa cuando el puntero entra en una opción.
`groupConfig`	`NeuOptionGroupConfig<T, G> \| null`	`null`	`[groupConfig]`	Accessors que leen las etiquetas, hijos y estado deshabilitado de los grupos.
`groups`	`readonly G[]`	`[]`	`[groups]`	Opciones agrupadas, con sus elementos hijos definidos mediante groupConfig.
`hidden`	`boolean`	`false`	`[hidden]`	Oculta el control según el estado del formulario.
`highlightOnSelect`	`boolean`	`true`	`[highlightOnSelect]`	Resalta las filas de opciones seleccionadas.
`hint`	`string`	`''`	`[hint]`	Texto de ayuda asociado al campo.
`id`	`string \| null`	`null`	`[id]`	Identificador del contenedor del control.
`invalid`	`boolean`	`false`	`[invalid]`	Muestra el estado inválido; no añade una regla de validación.
`label`	`string`	`''`	`[label]`	Etiqueta visible del campo o de la opción.
`lazy`	`boolean`	`false`	`[lazy]`	Usa ventanas cargadas y emite solicitudes de los datos de opciones que faltan.
`listStyle`	`Record<string, string \| number> \| null`	`null`	`[listStyle]`	Estilos en línea para el área visible de la lista.
`listStyleClass`	`string \| null`	`null`	`[listStyleClass]`	Clase CSS adicional para el área visible de la lista.
`loading`	`boolean`	`false`	`[loading]`	Muestra el estado de carga mientras la aplicación proporciona datos.
`metaKeySelection`	`boolean`	`false`	`[metaKeySelection]`	Controla si la selección utiliza la tecla modificadora de la plataforma.
`mode`	`M`	`'single' as M`Valor derivado	`[mode]`	Modo de selección. El tipo del valor depende del modo elegido.
`name`	`string`	`''`	`[name]`	Nombre asociado al control nativo del formulario.
`noResultsMessage`	`string`	`'No results found'`	`[noResultsMessage]`	Mensaje que se muestra cuando el filtro no encuentra coincidencias.
`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.
`options`	`readonly T[]`	`[]`	`[options]`	Registros de opciones cargados. Los accessors permiten usar tus propios objetos de dominio.
`optionValue`	`(option: T) => V`	`(option) => resolveNeuOptionValue<T, V>(option)`Valor derivado	`[optionValue]`	Nombre de campo o función que obtiene el valor guardado de la opción.
`pending`	`boolean`	`false`	`[pending]`	Estado del formulario que indica que hay una validación asíncrona pendiente.
`readonly`	`boolean`	`false`	`[readonly]`	Mantiene el valor visible sin permitir que el usuario lo cambie.
`required`	`boolean`	`false`	`[required]`	Marca el campo como obligatorio; utiliza un validador del formulario para exigirlo.
`scrollHeight`	`string`	`'18rem'`	`[scrollHeight]`	Altura máxima del área visible de opciones.
`searchable`	`boolean`	`false`	`[searchable]`	Muestra el campo de búsqueda de opciones integrado.
`searchPlaceholder`	`string`	`'Search...'`	`[searchPlaceholder]`	Placeholder del campo de búsqueda de opciones.
`selectOnFocus`	`boolean`	`false`	`[selectOnFocus]`	Selecciona la opción al mover el foco, sin esperar a su activación.
`showToggleAll`	`boolean`	`true`	`[showToggleAll]`	Muestra la acción de seleccionar todo en el modo múltiple con checkbox.
`striped`	`boolean`	`false`	`[striped]`	Alterna el fondo de las filas de opciones.
`tabindex`	`number`	`0`	`[tabindex]`	Orden de tabulación del punto de entrada por teclado.
`toggleAllLabel`	`string`	`'Select all visible options'`	`[toggleAllLabel]`	Nombre accesible y visible de la acción de seleccionar todo.
`totalItems`	`number \| null`	`null`	`[totalItems]`	Número total lógico de opciones en las ventanas remotas.
`touched`	`boolean`	`false`	`[touched]`	Estado del formulario que indica que el control ha sido visitado.
`virtualScroll`	`boolean`	`false`	`[virtualScroll]`	Renderiza una ventana de opciones en lugar de todas las opciones.
`virtualScrollBuffer`	`number`	`3`	`[virtualScrollBuffer]`	Opciones adicionales renderizadas antes y después de la ventana virtual visible.
`virtualScrollItemSize`	`number`	`40`	`[virtualScrollItemSize]`	Altura de cada fila de opción en píxeles para el scroll virtual.
`virtualScrollViewportItems`	`number`	`8`	`[virtualScrollViewportItems]`	Número de filas del área visible virtual.

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
`dataRequest`	`NeuOptionDataRequest`	`(dataRequest)="onDataRequest($event)"`	Solicita una ventana de opciones. La aplicación proporciona options, dataFirst y totalItems.
`drop`	`NeuListboxDropEvent<T>`	`(drop)="onDrop($event)"`	Resultado de arrastrar y soltar. Aplica las opciones reordenadas desde la aplicación.
`filterChange`	`string`	`(filterChange)="onFilterChange($event)"`	Consulta de búsqueda del usuario. Úsala para actualizar un filtro controlado o pedir resultados remotos.
`focusEntered`	`FocusEvent`	`(focusEntered)="onFocusEntered($event)"`	Se emite cuando el foco entra en el control.
`focusLeft`	`FocusEvent`	`(focusLeft)="onFocusLeft($event)"`	Se emite cuando el foco sale del control.
`optionActivated`	`NeuOptionActivatedEvent<T, V>`	`(optionActivated)="onOptionActivated($event)"`	Opción activada, su valor y el evento que la ha activado.
`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
`NeuListboxEmptyDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxEmpty]`
`NeuListboxEmptyFilterDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxEmptyFilter]`
`NeuListboxFilterDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxFilter]`
`NeuListboxFooterDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxFooter]`
`NeuListboxGroupDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxGroup]`
`NeuListboxHeaderDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxHeader]`
`NeuListboxIndicatorDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxIndicator]`
`NeuListboxItemDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxItem]`
`NeuListboxLoaderDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuListboxLoader]`

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

Template Empty

NeuListboxEmptyDirective

Abre el control para ver el estado vacío.

Destino

Todavía no hay destinos disponibles.