InputTags | Neural UI v2

Usage

The model is a readonly array of values. Enter or a separator commits a token; typing a draft alone does not change the array. options and typeahead add suggestions. Use optionLabel/optionValue with objects, compareWith for identity and textValue to parse free text into domain values.

Examples

Interact with the example and open Code for its complete implementation.

Topics

Angular

Choose a suggestion or press Enter to add text. Paste comma-separated topics to add several; duplicates are excluded by default.

Tags and paste result

Try and configure

Change the controls and try the live preview. Expand the application value or event to inspect its real data; the generated template stays with the configurator.

Live preview

Topics

Angular

Current application value

Generated template: the options above. The Code tab contains the imports and state.

<neu-input-tags
  [(value)]="tags"
  [options]="topics"
  [typeahead]="true"
  [allowDuplicates]="false"
  [commitOnBlur]="false"
  size="md"
  [delay]="0"
  [emptyMessage]="'No matching topics'"
  [fluid]="true"
  [label]="'Topics'"
  [placeholder]="'Add a topic'"
/>

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 tags = signal([
  "Angular"
]);

export const topics = [
  "Angular",
  "Signals",
  "TypeScript",
  "CSS"
];

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 · NeuOptionCompareWith<V>

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

groups · readonly NeuInputTagsGroup<T>[]

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

normalizeToken · (text: string) => string

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

separators · readonly string[]

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

textValue · ((text: string) => V | null | undefined) | null

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

Signal Forms

Bind FormField once to the component; the field owns value and validation. The schema requires a non-empty value. Leave the control to mark it touched, then reset the field to clear both value and interaction state.

Signal Forms guide

Topics

Valid: true

Form value

Value and events

Use [(value)] or [value] with (valueChange), not both. The model synchronizes application state; other Outputs communicate their documented events. touch reports leaving/visiting the control, not a new value.

Accessibility and keyboard

The visible label names the text field. Give removal buttons a descriptive removeLabel; custom item templates must preserve an accessible remove action. Arrow keys navigate suggestions, Enter adds a token and Escape closes the panel. readonly allows inspecting values without adding or removing tags.

Key	Action
`Tab`	Enters and leaves the control.
`Enter`	Commits a text token or highlighted suggestion.
`Backspace / Delete`	Edits text or removes a focused tag.
`Escape`	Closes the suggestions panel.

API

Inputs, models and Outputs come from the pinned Core contract. Click named types to open their definitions. Each Template below includes its own live example and 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
`allowDuplicates`	`boolean`	`false`	`[allowDuplicates]`	Allows repeated committed values; otherwise compareWith excludes duplicates.
`ariaDescribedBy`	`string`	`''`	`[ariaDescribedBy]`	IDs of elements describing the control, separated by spaces.
`ariaLabel`	`string`	`''`	`[ariaLabel]`	Accessible name when no visible label is available.
`ariaLabelledBy`	`string`	`''`	`[ariaLabelledBy]`	ID of the element that supplies the accessible name.
`ariaRequired`	`boolean`	`false`	`[ariaRequired]`	Accessible required state; it does not install a validator.
`autocomplete`	`string`	`'off'`	`[autocomplete]`	Native browser autocomplete attribute for the input.
`autofocus`	`boolean`	`false`	`[autofocus]`	Requests focus when the control is initialized.
`autoOptionFocus`	`boolean`	`false`	`[autoOptionFocus]`	Moves the active option to an available option when the list opens.
`commitOnBlur`	`boolean`	`false`	`[commitOnBlur]`	Commits the current text draft when focus leaves the composite control.
`compareWith`	`NeuOptionCompareWith<V>`	`Object.is`Derived default	`[compareWith]`	Comparison function for selected values; use stable domain identity.
`completeOnFocus`	`boolean`	`false`	`[completeOnFocus]`	Requests matching suggestions when focus enters the control.
`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]`	Prevents user interaction.
`emptyMessage`	`string`	`'No suggestions'`	`[emptyMessage]`	Message displayed when the option collection is empty.
`errors`	`readonly ValidationError.WithOptionalFieldTree[]`	`[]`	`[errors]`	Validation errors supplied by the form or the application.
`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.
`groups`	`readonly NeuInputTagsGroup<T>[]`	`[]`	`[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.
`inputId`	`string`	`''`	`[inputId]`	Stable identifier of the native control; automatically generated when omitted.
`invalid`	`boolean`	`false`	`[invalid]`	Displays the invalid state; it does not add a validation rule.
`label`	`string`	`''`	`[label]`	Visible label and accessible name of the control.
`loading`	`boolean`	`false`	`[loading]`	Displays the loading state while the application supplies data.
`maxItems`	`number \| null`	`null`	`[maxItems]`	Maximum committed tag count, or null for no limit.
`maxlength`	`number \| null`	`null`	`[maxlength]`	Maximum native draft-text length, or null for no limit.
`minlength`	`number \| null`	`null`	`[minlength]`	Minimum native draft-text length, or null when unspecified.
`minQueryLength`	`number`	`1`	`[minQueryLength]`	Minimum draft length before requesting suggestions.
`name`	`string`	`''`	`[name]`	Name associated with the native form control.
`normalizeToken`	`(text: string) => string`	`(text) => text.trim()`Derived default	`[normalizeToken]`	Normalizes free-text tokens before parsing and duplicate comparison. Defaults to trim.
`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.
`pending`	`boolean`	`false`	`[pending]`	Form state indicating that asynchronous validation is pending.
`placeholder`	`string`	`'Add tag...'`	`[placeholder]`	Text shown when the field has no selected value.
`readonly`	`boolean`	`false`	`[readonly]`	Keeps the control focusable and readable without accepting edits.
`removeLabel`	`string`	`'Remove'`	`[removeLabel]`	Accessible label prefix for removing a tag.
`required`	`boolean`	`false`	`[required]`	Marks the field as required; use a form validator to enforce it.
`scrollHeight`	`string`	`'200px'`	`[scrollHeight]`	Maximum height of the option viewport.
`separators`	`readonly string[]`	`[',']`	`[separators]`	Characters that commit a draft or split pasted text into tokens. Defaults to comma.
`size`	`"sm" \| "md" \| "lg"`	`'md'`	`[size]`	Visual field size: sm, md or lg.
`tabindex`	`number \| null`	`null`	`[tabindex]`	Tab order of the keyboard entry point.
`textValue`	`((text: string) => V \| null \| undefined) \| null`	`null`	`[textValue]`	Converts free text into a value. Returning null/undefined rejects the token.
`title`	`string`	`''`	`[title]`	Native tooltip text for the text field.
`touched`	`boolean`	`false`	`[touched]`	Form state indicating that the control has been visited.
`typeahead`	`boolean`	`false`	`[typeahead]`	Enables the suggestion panel backed by options or groups.
`variant`	`"outline" \| "solid"`	`'outline'`	`[variant]`	Visual field variant: outline or solid.

Models

A model supports [(property)]="signal" or the [property] and (propertyChange) pair. Choose one form, not both.

Name	Type	Default	Template binding	Description
`value`	`readonly V[]`	`[]`	`[(value)]`	Readonly array of committed tag values; the draft is separate.

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`	`NeuInputTagsClearedEvent<V>`	`(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.
`focusEntered`	`FocusEvent`	`(focusEntered)="onFocusEntered($event)"`	Emitted when focus enters the control.
`focusLeft`	`FocusEvent`	`(focusLeft)="onFocusLeft($event)"`	Emitted when focus leaves the control.
`itemRemoved`	`NeuInputTagsRemovedEvent<V>`	`(itemRemoved)="onItemRemoved($event)"`	Reports the removed item and index; valueChange already synchronizes the array.
`itemReordered`	`NeuInputTagsReorderedEvent<V>`	`(itemReordered)="onItemReordered($event)"`	Reports a reordered item; valueChange synchronizes the new array order.
`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.
`pasteResult`	`NeuInputTagsPasteResult<V>`	`(pasteResult)="onPasteResult($event)"`	Reports accepted and rejected pasted tokens after processing.
`suggestionsRequest`	`NeuOptionDataRequest`	`(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
`NeuInputTagsFooterDirective`View example	Public template directive (entrypoint)	`ng-template[neuInputTagsFooter]`
`NeuInputTagsGroupDirective`View example	Public template directive (entrypoint)	`ng-template[neuInputTagsGroup]`
`NeuInputTagsHeaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuInputTagsHeader]`
`NeuInputTagsItemDirective`View example	Public template directive (entrypoint)	`ng-template[neuInputTagsItem]`
`NeuInputTagsOptionDirective`View example	Public template directive (entrypoint)	`ng-template[neuInputTagsOption]`
`NeuInputTagsRemoveIconDirective`View example	Public template directive (entrypoint)	`ng-template[neuInputTagsRemoveIcon]`

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

Group template

NeuInputTagsGroupDirective

Topics

Angular

Header template

NeuInputTagsHeaderDirective

Topics

Angular

Item template

NeuInputTagsItemDirective

Topics

Angular

Option template

NeuInputTagsOptionDirective

Topics

Angular

RemoveIcon template

NeuInputTagsRemoveIconDirective

Topics

Angular

Public Types

Open a type to inspect its definition and interface fields.

NeuIndexRangeTypeScript

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

// Public declaration (reference only)
export interface NeuIndexRange {
  readonly end: number;
  readonly start: number;
}

NeuInputTagsClearedEventTypeScript

import type { NeuInputTagsClearedEvent } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsClearedEvent<V> {
  readonly originalEvent: Event;
  readonly previousValue: readonly V[];
}

NeuInputTagsGroupTypeScript

import type { NeuInputTagsGroup } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsGroup<T> {
  readonly disabled?: boolean;
  readonly label: string;
  readonly options: readonly T[];
}

NeuInputTagsGroupTemplateContextTypeScript

import type { NeuInputTagsGroup } from '@neural-ui/core/input-tags';

import type { NeuInputTagsGroupTemplateContext } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsGroupTemplateContext<T> {
  readonly $implicit: NeuInputTagsGroup<T>;
  readonly group: NeuInputTagsGroup<T>;
}

NeuInputTagsItemTemplateContextTypeScript

import type { NeuInputTagsItemTemplateContext } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsItemTemplateContext<T, V> {
  readonly $implicit: V;
  readonly index: number;
  readonly onRemove: (event: Event, index: number) => void;
  readonly option: T | null;
  readonly value: V;
}

NeuInputTagsOptionTemplateContextTypeScript

import type { NeuInputTagsOptionTemplateContext } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsOptionTemplateContext<T, V> {
  readonly $implicit: T;
  readonly index: number;
  readonly option: T;
  readonly value: V;
}

NeuInputTagsPasteResultTypeScript

import type { NeuInputTagsPasteResult } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsPasteResult<V> {
  readonly accepted: readonly V[];
  readonly originalEvent: ClipboardEvent;
  readonly rejected: readonly string[];
}

NeuInputTagsRemovedEventTypeScript

import type { NeuInputTagsRemovedEvent } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsRemovedEvent<V> {
  readonly index: number;
  readonly originalEvent: Event;
  readonly value: V;
}

NeuInputTagsReorderedEventTypeScript

import type { NeuInputTagsReorderedEvent } from '@neural-ui/core/input-tags';

// Public declaration (reference only)
export interface NeuInputTagsReorderedEvent<V> {
  readonly from: number;
  readonly originalEvent: Event;
  readonly to: number;
  readonly value: V;
}

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

NeuOptionCompareWithTypeScript

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

// Public declaration (reference only)
export type NeuOptionCompareWith<V> = (left: V, right: V) => boolean;

NeuOptionDataRequestTypeScript

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

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

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

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

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

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

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

This component uses shared theme tokens rather than dedicated component hooks.

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-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-radius`	Control corner radius	Shared by other Core consumers; scope the override.	`8px`
`--neu-surface`	Main field, header or control surface	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-surface-2`	Secondary surfaces and alternating rows	Shared by other Core consumers; scope the override.	`#f1f5f9`

Related components

Use the related controls for a different kind of value or interaction.

Live preview

Inputs

Models

Outputs

Templates

Footer template

Group template

Header template

Item template

Option template

RemoveIcon template

Public Types

Specific tokens

Shared tokens used