Autocomplete | Neural UI v2

Usage

Autocomplete separates typed query text from the selected value. In strict mode the user selects an available suggestion; free-text mode also accepts text that is not in the collection.

The example handles queryChange synchronously and supplies matching suggestions. For remote data, handle suggestionsRequest and provide the response through suggestions; query text is not itself a confirmed selection.

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

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

<neu-autocomplete
  [options]="destinations"
  [suggestions]="suggestions()"
  (queryChange)="query.set($event)"
  (suggestionsRequest)="refreshSuggestions($event.query)"
  [(value)]="destination"
  [dropdown]="true"
  [clearAriaLabel]="'Clear selection'"
  [delay]="0"
  [dropdownAriaLabel]="'Show destinations'"
  [emptyLabel]="'No matches'"
  [floatingLabel]="true"
  [fluid]="true"
  [label]="'Destination'"
  [listAriaLabel]="'Destination'"
  [loadingLabel]="'Loading destinations'"
  [placeholder]="'Choose a destination'"
/>

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 suggestions = signal([
  {
    "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).

groupSuggestions · readonly G[] | null

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

options · readonly T[]

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

optionValue · NeuOptionValueAccessor<T, V> | null

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

pattern · readonly RegExp[]

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

value · NeuAutocompleteValue<V, F>

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
`ariaDescribedBy`	`string \| null`	`null`	`[ariaDescribedBy]`	IDs of elements describing the control, separated by spaces.
`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`	`'off'`	`[autocomplete]`	Native browser autocomplete attribute for the input.
`autofocus`	`boolean`	`false`	`[autofocus]`	Requests focus when the control is initialized.
`autoHighlight`	`boolean`	`false`	`[autoHighlight]`	Automatically highlights the first available suggestion.
`autoOptionFocus`	`boolean`	`false`	`[autoOptionFocus]`	Moves the active option to an available option when the list opens.
`clearable`	`boolean`	`true`	`[clearable]`	Shows a clear action when a value is selected.
`clearAriaLabel`	`string`	`'Clear value'`	`[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.
`completeOnFocus`	`boolean`	`false`	`[completeOnFocus]`	Requests suggestions when the input receives focus.
`dataFirst`	`number`	`0`	`[dataFirst]`	Logical index of the first loaded option in a remote window.
`delay`	`number`	`300`	`[delay]`	Debounce time in milliseconds before requesting suggestions.
`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.
`dropdown`	`boolean`	`false`	`[dropdown]`	Shows a button that opens or requests suggestions.
`dropdownAriaLabel`	`string`	`'Show suggestions'`	`[dropdownAriaLabel]`	Accessible name of the suggestions button.
`dropdownMode`	`NeuAutocompleteDropdownMode`	`'blank'`	`[dropdownMode]`	Uses the current query or an empty query for dropdown requests.
`emptyLabel`	`string`	`'No results'`	`[emptyLabel]`	Message displayed when there are no available options.
`emptySelectionMessage`	`string`	`'No selected item'`	`[emptySelectionMessage]`	Announcement when no option is selected.
`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.
`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.
`groupSuggestions`	`readonly G[] \| null`	`null`	`[groupSuggestions]`	Enables grouped suggestion rendering.
`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.
`inputSize`	`number \| null`	`null`	`[inputSize]`	Native input size attribute, independent of the visual size variant.
`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.
`listAriaLabel`	`string`	`'Suggestions'`	`[listAriaLabel]`	Accessible name of the suggestions list.
`loading`	`boolean`	`false`	`[loading]`	Displays the loading state while the application supplies data.
`loadingLabel`	`string`	`'Loading...'`	`[loadingLabel]`	Message or announcement for loading options.
`maxLength`	`number \| undefined`	`undefined`	`[maxLength]`	Maximum native text input length.
`minLength`	`number \| undefined`	`undefined`	`[minLength]`	Minimum native text input length.
`minQueryLength`	`number`	`0`	`[minQueryLength]`	Minimum query length before requesting suggestions.
`mode`	`F`	`'strict' as F`Derived default	`[mode]`	strict selects an available suggestion; free-text also accepts arbitrary text.
`name`	`string`	`''`	`[name]`	Name associated with the native form control.
`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`	`NeuOptionValueAccessor<T, V> \| null`	`null`	`[optionValue]`	Field name or function used to obtain the stored option value.
`pattern`	`readonly RegExp[]`	`[]`	`[pattern]`	Native pattern attribute for text input.
`pending`	`boolean`	`false`	`[pending]`	Form state indicating that asynchronous validation is pending.
`placeholder`	`string`	`''`	`[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.
`scrollHeight`	`string`	`'240px'`	`[scrollHeight]`	Maximum height of the option viewport.
`searchMessage`	`string \| null`	`null`	`[searchMessage]`	Accessible announcement describing the search result count.
`selectionMessage`	`string`	`'{0} item selected'`	`[selectionMessage]`	Accessible announcement describing the selected option.
`selectOnFocus`	`boolean`	`false`	`[selectOnFocus]`	Selects the option as focus moves, rather than waiting for activation.
`showEmptyMessage`	`boolean`	`true`	`[showEmptyMessage]`	Shows the empty-suggestions message.
`size`	`NeuAutocompleteSize`	`'md'`	`[size]`	Visual field size: sm, md or lg.
`suggestions`	`readonly T[] \| null`	`null`	`[suggestions]`	Suggestion records supplied for the current query.
`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.
`type`	`string`	`'text'`	`[type]`	Native text input type.
`variant`	`NeuAutocompleteVariant`	`'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`	`NeuAutocompleteValue<V, F>`	`null as NeuAutocompleteValue<V, F>`Derived default	`[(value)]`	Confirmed value or null; free-text mode also accepts a string. queryChange carries search text.

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`	`NeuAutocompleteClearEvent<V, F>`	`(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.
`dropdownClick`	`NeuAutocompleteDropdownClickEvent`	`(dropdownClick)="onDropdownClick($event)"`	Describes the query and source of the suggestions-button action.
`focusEntered`	`FocusEvent`	`(focusEntered)="onFocusEntered($event)"`	Emitted when focus enters the control.
`focusLeft`	`FocusEvent`	`(focusLeft)="onFocusLeft($event)"`	Emitted when focus leaves the control.
`inputKeydown`	`KeyboardEvent`	`(inputKeydown)="onInputKeydown($event)"`	Native keydown event from the text input.
`keyUp`	`KeyboardEvent`	`(keyUp)="onKeyUp($event)"`	Native keyup event from the text input.
`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.
`queryChange`	`string`	`(queryChange)="onQueryChange($event)"`	Current text query, distinct from the selected value.
`suggestionsRequest`	`NeuAutocompleteSuggestionsRequest`	`(suggestionsRequest)="onSuggestionsRequest($event)"`	Requests suggestions with query and request identity; the application supplies suggestions.
`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
`NeuAutocompleteClearIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteClearIcon]`
`NeuAutocompleteDropdownIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteDropdownIcon]`
`NeuAutocompleteEmptyDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteEmpty]`
`NeuAutocompleteFooterDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteFooter]`
`NeuAutocompleteGroupDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteGroup]`
`NeuAutocompleteHeaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteHeader]`
`NeuAutocompleteItemDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteItem]`
`NeuAutocompleteLoaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteLoader]`
`NeuAutocompleteLoadingIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuAutocompleteLoadingIcon]`

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

ClearIcon template

NeuAutocompleteClearIconDirective

Use the dropdown button or type to open the suggestions.

Destination

Empty template

NeuAutocompleteEmptyDirective

Open the control to see the empty state.

Destination

Group template

NeuAutocompleteGroupDirective

Use the dropdown button or type to open the suggestions.

Destination

Header template

NeuAutocompleteHeaderDirective

Use the dropdown button or type to open the suggestions.

Destination

Item template

NeuAutocompleteItemDirective

Use the dropdown button or type to open the suggestions.

Destination

Loader template

NeuAutocompleteLoaderDirective

Use the dropdown button or type to open the suggestions.

Destination

LoadingIcon template

NeuAutocompleteLoadingIconDirective

Use the dropdown button or type to open the suggestions.

Destination

Public methods

Name	Contract
`clear`	`clear(originalEvent?: Event \| null, reason?: 'button' \| 'force-selection' \| 'programmatic'): void;`
`close`	`close(originalEvent?: Event \| null, reason?: OverlayReason, restoreFocus?: boolean): void;`
`focus`	`focus(): void;`
`open`	`open(originalEvent?: Event \| null, reason?: OverlayReason): void;`
`openAll`	`openAll(event?: Event \| null): void;`
`reset`	`reset(): void;`
`selectOption`	`selectOption(option: T, originalEvent?: Event \| null): void;`

Public Types

Open a type to inspect its definition and interface fields.

NeuAutocompleteClearEventTypeScript

import type { NeuAutocompleteMode } from '@neural-ui/core/autocomplete';
import type { NeuAutocompleteValue } from '@neural-ui/core/autocomplete';

import type { NeuAutocompleteClearEvent } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteClearEvent<V, F extends NeuAutocompleteMode = 'strict'> {
  readonly originalEvent: Event | null;
  readonly previousText: string;
  readonly previousValue: NeuAutocompleteValue<V, F>;
  readonly reason: 'button' | 'input' | 'force-selection' | 'programmatic';
}

NeuAutocompleteCompleteEventTypeScript

import type { NeuAutocompleteCompletionSource } from '@neural-ui/core/autocomplete';

import type { NeuAutocompleteCompleteEvent } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteCompleteEvent {
  readonly originalEvent: Event | null;
  readonly query: string;
  readonly requestId: number;
  readonly source: NeuAutocompleteCompletionSource;
}

NeuAutocompleteCompletionSourceTypeScript

import type { NeuAutocompleteCompletionSource } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteCompletionSource = 'input' | 'focus' | 'dropdown' | 'programmatic';

NeuAutocompleteDropdownClickEventTypeScript

import type { NeuAutocompleteDropdownMode } from '@neural-ui/core/autocomplete';

import type { NeuAutocompleteDropdownClickEvent } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteDropdownClickEvent {
  readonly mode: NeuAutocompleteDropdownMode;
  readonly originalEvent: Event;
  readonly query: string;
}

NeuAutocompleteDropdownModeTypeScript

import type { NeuAutocompleteDropdownMode } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteDropdownMode = 'blank' | 'current';

NeuAutocompleteGroupContextTypeScript

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

import type { NeuAutocompleteGroupContext } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteGroupContext<G> = NeuOptionGroupTemplateContext<G>;

NeuAutocompleteIconContextTypeScript

import type { NeuAutocompleteIconContext } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteIconContext {
  readonly $implicit: boolean;
  readonly active: boolean;
}

NeuAutocompleteItemContextTypeScript

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

import type { NeuAutocompleteItemContext } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteItemContext<T, V = unknown> extends NeuOptionTemplateContext<T> {
  readonly label: string;
  readonly value: V;
}

NeuAutocompleteLoaderContextTypeScript

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

import type { NeuAutocompleteLoaderContext } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteLoaderContext = NeuOptionLoaderTemplateContext;

NeuAutocompleteModeTypeScript

import type { NeuAutocompleteMode } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteMode = 'strict' | 'free-text';

NeuAutocompleteOptionTypeScript

import type { NeuAutocompleteOption } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteOption<V = unknown> {
  readonly disabled?: boolean;
  readonly label: string;
  readonly value: V;
}

NeuAutocompleteOverlayEventTypeScript

import type { NeuAutocompleteOverlayEvent } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteOverlayEvent {
  readonly originalEvent: Event | null;
  readonly reason: 'completion' | 'focus' | 'dropdown' | 'keyboard' | 'selection' | 'clear' | 'escape' | 'outside' | 'tab' | 'programmatic';
}

NeuAutocompleteSelectEventTypeScript

import type { NeuAutocompleteSelectEvent } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteSelectEvent<T, V> {
  readonly option: T;
  readonly originalEvent: Event | null;
  readonly value: V;
}

NeuAutocompleteSizeTypeScript

import type { NeuAutocompleteSize } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteSize = 'sm' | 'md' | 'lg';

NeuAutocompleteSuggestionsRequestTypeScript

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

import type { NeuAutocompleteSuggestionsRequest } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export interface NeuAutocompleteSuggestionsRequest {
  readonly query: string;
  readonly queryRevision: number;
  readonly range?: NeuViewportRange;
  readonly reason: 'initial' | 'query' | 'viewport' | 'retry';
  readonly requestId: number;
  readonly source: NeuAutocompleteCompletionSource;
}

NeuAutocompleteValueTypeScript

import type { NeuAutocompleteMode } from '@neural-ui/core/autocomplete';

import type { NeuAutocompleteValue } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteValue<V, F extends NeuAutocompleteMode = 'strict'> = F extends 'free-text' ? V | string | null : V | null;

NeuAutocompleteVariantTypeScript

import type { NeuAutocompleteVariant } from '@neural-ui/core/autocomplete';

// Public declaration (reference only)
export type NeuAutocompleteVariant = 'outline' | 'solid';

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);

NeuOptionActivatedEventTypeScript

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

// Public declaration (reference only)
export interface NeuOptionActivatedEvent<T, V> {
  readonly option: T;
  readonly originalEvent?: Event;
  readonly source: 'pointer' | 'keyboard';
  readonly value: V;
}

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>;

NeuOptionFilterConfigTypeScript

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

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

// Public declaration (reference only)
export interface NeuOptionFilterConfig<T> {
  readonly fields?: readonly NeuOptionAccessor<T, unknown>[];
  readonly locale?: string;
  readonly matchMode?: NeuOptionFilterMatchMode;
  readonly strategy?: NeuOptionFilterStrategy;
}

NeuOptionFilterMatchModeTypeScript

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

// Public declaration (reference only)
export type NeuOptionFilterMatchMode = 'startsWith' | 'contains' | 'notContains' | 'endsWith' | 'equals' | 'notEquals';

NeuOptionFilterStrategyTypeScript

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

// Public declaration (reference only)
export type NeuOptionFilterStrategy = 'client' | 'server';

NeuOptionGroupConfigTypeScript

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

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

// Public declaration (reference only)
export interface NeuOptionGroupConfig<T, G> {
  readonly childrenAccessor: NeuOptionAccessor<G, readonly T[]>;
  readonly disabledAccessor?: NeuOptionAccessor<G, boolean> | null;
  readonly labelAccessor: NeuOptionAccessor<G, unknown>;
}

NeuOptionGroupTemplateContextTypeScript

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

// Public declaration (reference only)
export interface NeuOptionGroupTemplateContext<G> {
  readonly $implicit: G;
  readonly disabled: boolean;
  readonly group: G;
  readonly index: number;
  readonly label: string;
}

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>;

NeuOptionLoaderTemplateContextTypeScript

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

// Public declaration (reference only)
export interface NeuOptionLoaderTemplateContext {
  readonly $implicit: number;
  readonly count: number;
  readonly end: number;
  readonly first: number;
  readonly logicalIndex: number;
}

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}`;

NeuOptionTemplateContextTypeScript

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

// Public declaration (reference only)
export interface NeuOptionTemplateContext<T> {
  readonly $implicit: T;
  readonly active: boolean;
  readonly disabled: boolean;
  readonly index: number;
  readonly logicalIndex: number;
  readonly option: T;
  readonly selected: boolean;
}

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>;

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

Token	Purpose	State / variant	Default / source	Fallback
`--neu-autocomplete-option-height`	Inherited theme value used by this component	Field surface	`40px`Root declaration	`No token alias`

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-border-hover`	Control borders on hover	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.16)`
`--neu-error`	Invalid field or danger-action color	Shared by other Core consumers; scope the override.	`#dc2626`
`--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-primary-50`	Subtle brand surface for hover and focus states	Shared by other Core consumers; scope the override.	`#eff6ff`
`--neu-primary-dark`	Dark brand shade; outline and ghost Button text in the light theme	Shared by other Core consumers; scope the override.	`#005fcc`
`--neu-radius`	Control corner radius	Shared by other Core consumers; scope the override.	`8px`

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

ClearIcon template

DropdownIcon template

Empty template

Footer template

Group template

Header template

Item template

Loader template

LoadingIcon template

Public methods

Public Types

Specific tokens

Shared tokens used