FORMSBETA

Select

A Signal-first combobox with object mapping, declarative options, all Angular Forms APIs, top-layer overlays and virtualized data.

Native combobox semanticsSSR safeHeadless ready

GET STARTED

Import

Import the public NeuralSelect class from the granular entry point.

import { NeuralSelect, OptionComponent } from '@neural-ng/core/select';

@Component({ imports: [NeuralSelect, OptionComponent] })

Data options and nested paths

Map labels, values, disabled state and icons without mutating source objects. Property accessors also accept nested paths.

City

Bursa demonstrates a disabled option.

No semantic event yet.

Primitive options

Strings and numbers need no label or value mapping.

Declarative options

neural-option owns rich projected content while its explicit label remains available to typeahead and assistive technology.

Angular Forms

One nullable value contract supports Signal Forms, Reactive Forms and template-driven Forms. Programmatic writes do not emit user-only selection events.

Signal Forms

Istanbul

Reactive Forms

Ankara

NgModel

Izmir

Chained selects

Compute dependent options from the first Signal and reset the child only on semantic user selection.

Province

District

States

Disabled, readonly, loading, empty and invalid states retain distinct interaction and ARIA contracts.

Required city

Selection is required.

Append to body

Use the browser top layer inside dialogs, tables and clipped containers. The shared positioner matches trigger width, flips and follows scroll or resize.

Virtual scroll

Large fixed-height lists render only the visible overscanned range while exposing complete set metadata to assistive technology.

Semantic events

valueChange is the model output; selection, clear, panel and touch events describe user intent without invented on-prefixed aliases.

<neural-select
  [(value)]="cityId"
  (valueChange)="valueChanged($event)"
  (selectionChange)="selected($event)"
  (cleared)="cleared($event)"
  (openChange)="panelChanged($event)"
  (touch)="touched()"
/>

Unstyled and typed class slots

Headless mode keeps combobox behavior, top-layer positioning, forms and structural hooks while consumer classes own every visible surface.

ACCESSIBILITY

Accessible by contract

The behavior follows the ARIA combobox/listbox interaction model without moving DOM focus into the popup.

Semantics

The native trigger exposes role=combobox, expanded state, controls and active descendant. Options expose selected, disabled, position and set size metadata.

Keyboard

Arrow Up/Down navigate enabled options; Home/End jump; Enter and Space select; Escape closes; Tab preserves natural focus order; printable keys provide buffered typeahead.

Naming and descriptions

Use neural-field for deterministic ids, labels, hints and errors, or provide ariaLabel directly. Loading is announced through aria-busy.

Readonly and disabled

Readonly remains focusable and inspectable but blocks mutation. Disabled uses the native disabled state and leaves the tab order. Disabled options are skipped by all navigation paths.

PUBLIC CONTRACT

Select API

Inputs

Name	Type	Default	Purpose
options	readonly TOption[]	[]	Data-driven options.
optionLabel	string	'label'	Display and accessible label path.
optionValue	string	'value'	Model value path.
optionDisabled	string	'disabled'	Disabled-state path.
optionIcon	string	'iconClass'	Option icon path.
value	TValue \| null	null	Two-way Signal model.
compareWith	function	Object.is	Custom value equality.
placeholder	string	'Select an option'	Empty value label.
emptyLabel	string	'No options available'	Empty list message.
loadingLabel	string	'Loading options'	Loading message.
clearLabel	string	'Clear selection'	Clear button accessible label.
ariaLabel	string	''	Combobox and listbox label.
selectId	string	''	Explicit trigger id.
iconClass	string	'nt-chevron-down'	Dropdown icon.
loadingIcon	string	'nt-loader-3 nt-spin'	Loading icon.
clearable	boolean	false	Shows clear action.
disabled	boolean	false	Disables the native trigger.
readonly	boolean	false	Focusable inspection without mutation.
required / invalid	boolean	false	ARIA and visual field states.
pending / touched / dirty	boolean	false	Forms state contract.
name	string	''	Template-driven name.
loading	boolean	false	Blocks interaction and announces busy.
virtualScroll	boolean	false	Overscanned visible range.
virtualItemSize	number	42	Fixed option height.
virtualScrollHeight	number	256	Viewport height.
virtualOverscan	number	3	Extra rendered rows.
fluid	boolean	false	Fills inline size.
appendTo	'self' \| 'body'	'self'	Panel ownership.
unstyled	boolean	false	Removes visual classes.
selectClass	string	''	Additive root class.
classes	NeuralSelectClasses	{}	Typed slot classes.

Outputs

valueChange	TValue \| null	Generated by the value model.
selectionChange	NeuralSelectChange	User selection with value, previous value, option and source.
cleared	NeuralSelectClear	Explicit clear action.
openChange	boolean	Panel visibility.
touch	void	Focus leaves the closed control.

Methods

focus(options?: FocusOptions) => void

Focuses the trigger.

reset() => void

Closes and restores null.

toggle() => void

Toggles when enabled.

Option API

neural-option requires value and label; it also accepts disabled and iconClass. Do not combine projected options with a non-empty options array.

Typed class slots

roottriggervalueplaceholderdropdownIconclearButtonpanellistoptionactiveOptionselectedOptiondisabledOptionoptionIconemptyMessageloadingMessage

DESIGN TOKENS

Select tokens

Neutral tokens respond to primary, surface and resolved light/dark mode. Consumer classes remain additive.

--neural-select-width

Trigger inline size.

--neural-select-min-height

Trigger minimum block size.

--neural-select-padding

Trigger internal spacing.

--neural-select-background

Trigger background surface.

--neural-select-background-hover

Hovered trigger background surface.

--neural-select-color

Trigger foreground color.

--neural-select-border

Trigger border shorthand.

--neural-select-border-color-hover

Hovered trigger border color.

--neural-select-border-color-focus

Focused trigger border color.

--neural-select-border-color-invalid

Invalid trigger border color.

--neural-select-radius

Trigger corner radius.

--neural-select-shadow-focus

Focused trigger box shadow.

--neural-select-focus-ring

Trigger keyboard focus ring.

--neural-select-placeholder-color

Placeholder foreground color.

--neural-select-panel-background

Panel background surface.

--neural-select-panel-border

Panel border shorthand.

--neural-select-panel-radius

Panel corner radius.

--neural-select-panel-shadow

Panel box shadow.

--neural-select-panel-max-height

Panel maximum block size.

--neural-select-option-color

Option foreground color.

--neural-select-option-background-active

Active option background surface.

--neural-select-option-background-selected

Selected option background surface.

--neural-select-option-color-selected

Selected option foreground color.

--neural-select-option-padding

Option internal spacing.

--neural-select-option-radius

Option corner radius.

--neural-select-disabled-opacity

Disabled opacity.

--neural-select-z-index

Trigger stacking order.

Primary

Surface