Listbox | Neural UI v2

Usage

Choose Listbox when the choices should remain visible rather than opening an overlay. Single and multiple modes use the same value contract as Select.

In multiple mode, checkbox indicators make selection explicit. Toggle-all affects visible enabled options. Virtual scrolling keeps the option viewport bounded for larger collections.

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 ·

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

<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]="'Search destinations'"
  [checkbox]="true"
  [emptyLabel]="'No destinations'"
  [fluid]="true"
  [label]="'Destination'"
  [noResultsMessage]="'No matches'"
  [searchPlaceholder]="'Search'"
/>

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": "madrid",
    "label": "Madrid"
  },
  {
    "value": "lisbon",
    "label": "Lisbon"
  },
  {
    "value": "paris",
    "label": "Paris"
  },
  {
    "value": "rome",
    "label": "Rome",
    "disabled": true
  }
];

export const destination = signal(null);

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.

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

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

errors · readonly ValidationError.WithOptionalFieldTree[]

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

filterConfig · Readonly<NeuOptionFilterConfig<T>>

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

groupConfig · NeuOptionGroupConfig<T, G> | null

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

groups · readonly G[]

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

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

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

mode · M

In Source: define mode with this type and use [mode]="mode" (or mode() 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 · (option: T) => V

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.

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
`ariaDescribedBy`	`string \| null`	`null`	`[ariaDescribedBy]`	IDs of elements describing the control, separated by spaces.
`ariaFilterLabel`	`string`	`'Filter options'`	`[ariaFilterLabel]`	Accessible name of the option search field.
`ariaLabel`	`string`	`'Options'`	`[ariaLabel]`	Accessible name when no visible label is available.
`ariaLabelledBy`	`string \| null`	`null`	`[ariaLabelledBy]`	ID of the element that supplies the accessible name.
`autoOptionFocus`	`boolean`	`true`	`[autoOptionFocus]`	Moves the active option to an available option when the list opens.
`checkbox`	`boolean`	`false`	`[checkbox]`	Displays checkbox indicators for multiple selection.
`checkmark`	`boolean`	`false`	`[checkmark]`	Displays a checkmark next to selected options.
`compareWith`	`(left: V, right: V) => boolean`	`Object.is`Derived default	`[compareWith]`	Comparison function for selected values; use stable domain identity.
`dataFirst`	`number`	`0`	`[dataFirst]`	Logical index of the first loaded option in a remote window.
`dirty`	`boolean`	`false`	`[dirty]`	Form state indicating that the user has changed the value.
`disabled`	`boolean`	`false`	`[disabled]`	Disables user interaction; disabled options cannot be selected.
`dragdrop`	`boolean`	`false`	`[dragdrop]`	Enables drag-and-drop between compatible listboxes.
`emptyLabel`	`string`	`'No options found'`	`[emptyLabel]`	Message displayed when there are no available options.
`errors`	`readonly ValidationError.WithOptionalFieldTree[]`	`[]`	`[errors]`	Validation errors supplied by the form or the application.
`filterConfig`	`Readonly<NeuOptionFilterConfig<T>>`	`{}`	`[filterConfig]`	Fields, matching mode, locale and client/server filtering strategy.
`filterValue`	`string \| null`	`null`	`[filterValue]`	Applied search query. Listen to filterChange when the application controls it.
`fluid`	`boolean`	`false`	`[fluid]`	Makes the control fill its containing width.
`focusOnHover`	`boolean`	`true`	`[focusOnHover]`	Changes the active option when the pointer enters an option.
`groupConfig`	`NeuOptionGroupConfig<T, G> \| null`	`null`	`[groupConfig]`	Accessors used to read group labels, children and disabled state.
`groups`	`readonly G[]`	`[]`	`[groups]`	Grouped options, with child items configured through groupConfig.
`hidden`	`boolean`	`false`	`[hidden]`	Hides the control according to the form state.
`highlightOnSelect`	`boolean`	`true`	`[highlightOnSelect]`	Highlights selected option rows.
`hint`	`string`	`''`	`[hint]`	Help text associated with the field.
`id`	`string \| null`	`null`	`[id]`	Identifier of the control host.
`invalid`	`boolean`	`false`	`[invalid]`	Displays the invalid state; it does not add a validation rule.
`label`	`string`	`''`	`[label]`	Visible field or option label.
`lazy`	`boolean`	`false`	`[lazy]`	Uses loaded windows and emits requests for missing option data.
`listStyle`	`Record<string, string \| number> \| null`	`null`	`[listStyle]`	Inline styles for the list viewport.
`listStyleClass`	`string \| null`	`null`	`[listStyleClass]`	Additional CSS class for the list viewport.
`loading`	`boolean`	`false`	`[loading]`	Displays the loading state while the application supplies data.
`metaKeySelection`	`boolean`	`false`	`[metaKeySelection]`	Controls whether selection uses the platform modifier key.
`mode`	`M`	`'single' as M`Derived default	`[mode]`	Selection mode. The accepted value shape follows the chosen mode.
`name`	`string`	`''`	`[name]`	Name associated with the native form control.
`noResultsMessage`	`string`	`'No results found'`	`[noResultsMessage]`	Message displayed when filtering produces no matches.
`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.
`options`	`readonly T[]`	`[]`	`[options]`	Loaded option records. Accessors allow using your own domain objects.
`optionValue`	`(option: T) => V`	`(option) => resolveNeuOptionValue<T, V>(option)`Derived default	`[optionValue]`	Field name or function used to obtain the stored option value.
`pending`	`boolean`	`false`	`[pending]`	Form state indicating that asynchronous validation is pending.
`readonly`	`boolean`	`false`	`[readonly]`	Keeps the value readable without allowing the user to change it.
`required`	`boolean`	`false`	`[required]`	Marks the field as required; use a form validator to enforce it.
`scrollHeight`	`string`	`'18rem'`	`[scrollHeight]`	Maximum height of the option viewport.
`searchable`	`boolean`	`false`	`[searchable]`	Displays the built-in option search field.
`searchPlaceholder`	`string`	`'Search...'`	`[searchPlaceholder]`	Placeholder for the option search field.
`selectOnFocus`	`boolean`	`false`	`[selectOnFocus]`	Selects the option as focus moves, rather than waiting for activation.
`showToggleAll`	`boolean`	`true`	`[showToggleAll]`	Shows the toggle-all action in checkbox multiple mode.
`striped`	`boolean`	`false`	`[striped]`	Alternates option row backgrounds.
`tabindex`	`number`	`0`	`[tabindex]`	Tab order of the keyboard entry point.
`toggleAllLabel`	`string`	`'Select all visible options'`	`[toggleAllLabel]`	Accessible and visible name of the toggle-all action.
`totalItems`	`number \| null`	`null`	`[totalItems]`	Logical total option count for remote windows.
`touched`	`boolean`	`false`	`[touched]`	Form state indicating that the control has been visited.
`virtualScroll`	`boolean`	`false`	`[virtualScroll]`	Renders an option window instead of every option.
`virtualScrollBuffer`	`number`	`3`	`[virtualScrollBuffer]`	Extra options rendered before and after the visible virtual window.
`virtualScrollItemSize`	`number`	`40`	`[virtualScrollItemSize]`	Measured option row height in pixels for virtual scrolling.
`virtualScrollViewportItems`	`number`	`8`	`[virtualScrollViewportItems]`	Number of rows in the virtual viewport.

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
`dataRequest`	`NeuOptionDataRequest`	`(dataRequest)="onDataRequest($event)"`	Requests an option window. The application supplies options, dataFirst and totalItems.
`drop`	`NeuListboxDropEvent<T>`	`(drop)="onDrop($event)"`	Drag-and-drop result. Apply the reordered options in the application.
`filterChange`	`string`	`(filterChange)="onFilterChange($event)"`	User search query. Use it to update a controlled filter or request remote results.
`focusEntered`	`FocusEvent`	`(focusEntered)="onFocusEntered($event)"`	Emitted when focus enters the control.
`focusLeft`	`FocusEvent`	`(focusLeft)="onFocusLeft($event)"`	Emitted when focus leaves the control.
`optionActivated`	`NeuOptionActivatedEvent<T, V>`	`(optionActivated)="onOptionActivated($event)"`	Activated option, its value and the originating event.
`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
`NeuListboxEmptyDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxEmpty]`
`NeuListboxEmptyFilterDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxEmptyFilter]`
`NeuListboxFilterDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxFilter]`
`NeuListboxFooterDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxFooter]`
`NeuListboxGroupDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxGroup]`
`NeuListboxHeaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxHeader]`
`NeuListboxIndicatorDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxIndicator]`
`NeuListboxItemDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxItem]`
`NeuListboxLoaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuListboxLoader]`

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

Empty template

NeuListboxEmptyDirective

Open the control to see the empty state.

Destination

No destinations are available yet.