Select | Neural UI v2

Usage

Use Select for a finite collection of choices. The default single mode stores one value or null; multiple mode stores an array. A disabled option remains visible but cannot be activated.

Use optionLabel, optionValue and optionDisabled for domain objects. Keep stable identifiers as values instead of copying the displayed label into application state.

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

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

Current application value

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

<neu-select
  [options]="destinations"
  (openChange)="onOpenChange($event)"
  (filterChange)="onFilterChange($event)"
  [(value)]="destination"
  [searchable]="true"
  [clearable]="true"
  [ariaFilterLabel]="'Search destinations'"
  [emptyMessage]="'No destinations'"
  [floatingLabel]="true"
  [fluid]="true"
  [label]="'Destination'"
  [loadingLabel]="'Loading destinations'"
  [noResultsMessage]="'No matches'"
  [placeholder]="'Choose a destination'"
  [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).

filterOptions · Readonly<NeuSelectFilterOptions>

In Source: define filterOptions with this type and use [filterOptions]="filterOptions" (or filterOptions() 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).

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 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
`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 \| null`	`null`	`[ariaLabel]`	Accessible name when no visible label is available.
`ariaLabelledBy`	`string \| null`	`null`	`[ariaLabelledBy]`	ID of the element that supplies the accessible name.
`autocomplete`	`string \| null`	`null`	`[autocomplete]`	Native browser autocomplete attribute for the input.
`autofocus`	`boolean`	`false`	`[autofocus]`	Requests focus when the control is initialized.
`autofocusFilter`	`boolean`	`false`	`[autofocusFilter]`	Focuses the search field when the panel opens.
`autoOptionFocus`	`boolean`	`true`	`[autoOptionFocus]`	Moves the active option to an available option when the list opens.
`checkmark`	`boolean`	`false`	`[checkmark]`	Displays a checkmark next to selected options.
`clearable`	`boolean`	`false`	`[clearable]`	Shows a clear action when a value is selected.
`clearAllLabel`	`string`	`'Clear all'`	`[clearAllLabel]`	Caption for clearing the selected options in the toggle-all scope.
`clearAriaLabel`	`string`	`'Clear selection'`	`[clearAriaLabel]`	Accessible name of the clear-selection button.
`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.
`emptyMessage`	`string`	`'No options available'`	`[emptyMessage]`	Message displayed when the option collection is empty.
`errorMessage`	`string`	`''`	`[errorMessage]`	Visible error message associated with the field.
`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.
`filterOptions`	`Readonly<NeuSelectFilterOptions>`	`{}`	`[filterOptions]`	Search settings: enabled state, debounce, locale and reset on close.
`filterValue`	`string \| null`	`null`	`[filterValue]`	Applied search query. Listen to filterChange when the application controls it.
`floatingLabel`	`boolean`	`false`	`[floatingLabel]`	Displays the label in the floating-label field style.
`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.
`hint`	`string`	`''`	`[hint]`	Help text associated with the field.
`id`	`string \| null`	`null`	`[id]`	Identifier of the control host.
`inputId`	`string \| null`	`null`	`[inputId]`	Identifier of the native input for label and accessibility associations.
`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.
`loading`	`boolean`	`false`	`[loading]`	Displays the loading state while the application supplies data.
`loadingLabel`	`string`	`'Loading...'`	`[loadingLabel]`	Message or announcement for loading options.
`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'`	`[noResultsMessage]`	Message displayed when filtering produces no matches.
`open`	`boolean \| undefined`	`undefined`	`[open]`	Applied panel visibility; update it in response to openChange for controlled opening.
`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.
`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.
`required`	`boolean`	`false`	`[required]`	Marks the field as required; use a form validator to enforce it.
`resetFilterOnHide`	`boolean`	`false`	`[resetFilterOnHide]`	Resets the search query when the panel closes.
`scrollHeight`	`string`	`'240px'`	`[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.
`selectAllLabel`	`string`	`'Select all'`	`[selectAllLabel]`	Caption for selecting enabled options in the toggle-all scope.
`selectionOptions`	`Readonly<NeuSelectSelectionOptions>`	`{}`	`[selectionOptions]`	Multiple-selection options: chips, selection limit, label count and toggle-all scope.
`selectOnFocus`	`boolean`	`false`	`[selectOnFocus]`	Selects the option as focus moves, rather than waiting for activation.
`size`	`NeuSelectSize`	`'md'`	`[size]`	Visual field size: sm, md or lg.
`tabindex`	`number`	`0`	`[tabindex]`	Tab order of the keyboard entry point.
`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.
`variant`	`NeuSelectVariant`	`'outline'`	`[variant]`	Visual field variant: outline or solid.
`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 \| null`	`null`	`[virtualScrollItemSize]`	Measured option row height in pixels for virtual scrolling.
`virtualScrollVisibleItems`	`number`	`8`	`[virtualScrollVisibleItems]`	Number of visible virtual rows.

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
`cleared`	`NeuSelectClearedEvent`	`(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.
`dataRequest`	`NeuOptionDataRequest`	`(dataRequest)="onDataRequest($event)"`	Requests an option window. The application supplies options, dataFirst and totalItems.
`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.
`openChange`	`boolean`	`(openChange)="onOpenChange($event)"`	Requested panel visibility; update open when visibility is controlled by the application.
`opened`	`void`	`(opened)="onOpened($event)"`	Emitted after the browser panel opens.
`optionActivated`	`NeuOptionActivatedEvent<T, V>`	`(optionActivated)="onOptionActivated($event)"`	Activated option, its value and the originating event.
`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
`NeuSelectClearIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectClearIcon]`
`NeuSelectDropdownIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectDropdownIcon]`
`NeuSelectEmptyDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectEmpty]`
`NeuSelectEmptyFilterDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectEmptyFilter]`
`NeuSelectFilterDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectFilter]`
`NeuSelectFilterIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectFilterIcon]`
`NeuSelectFooterDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectFooter]`
`NeuSelectGroupDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectGroup]`
`NeuSelectHeaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectHeader]`
`NeuSelectItemDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectItem]`
`NeuSelectLoaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectLoader]`
`NeuSelectLoadingIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectLoadingIcon]`
`NeuSelectSelectedDirective`View example	Public template directive (entrypoint)	`ng-template[neuSelectSelected]`

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