Input Tag

A tag / token multiselect. Type a value and press Enter to add a removable chip, or pick from an optional suggestion list. Form-associated via ElementInternals — the selected tokens submit with the enclosing form.

Inherited wc import '@esa/ecology/esa-input-tag';

Preview

<esa-input-tag label="Tags" placeholder="Add a tag"></esa-input-tag>

Suggestions

Pass an options array (as a property) to drive a filtered suggestion dropdown. Typed values and picked suggestions coexist — anything not in the list is added as a free-form token.

<esa-input-tag label="Species" placeholder="Search or add a species"></esa-input-tag>
<!-- el.options = [{ value, label }, ...] -->

Sizes

<esa-input-tag label="Extra small" size="xs"></esa-input-tag>
<esa-input-tag label="Small" size="sm"></esa-input-tag>
<esa-input-tag label="Medium" size="md"></esa-input-tag>
<esa-input-tag label="Large" size="lg"></esa-input-tag>

States

The required asterisk, helper text, and disabled state are attribute-driven. Disabled fields keep their chips but drop the remove buttons. error-text replaces help-text in the slot below the field and reddens the border, so the two never stack.

<esa-input-tag label="Required" required placeholder="At least one tag"></esa-input-tag>
<esa-input-tag label="With help" help-text="Press Enter to add each tag."></esa-input-tag>
<esa-input-tag label="With error" error-text="Add at least one tag."></esa-input-tag>
<esa-input-tag label="Disabled" disabled></esa-input-tag>

Form participation

The element is form-associated. Submitting logs the FormData entry for tags — a comma-joined list of token values.

<form>
  <esa-input-tag label="Tags" name="tags" placeholder="Add then submit"></esa-input-tag>
  <button type="submit">Submit</button>
</form>

API

Prop	Type	Default	Description
`label`	`string`	`''`	Visible label rendered above the field.
`help-text`	`string`	`''`	Helper text shown below the field. Property: `helpText`.
`error-text`	`string`	`''`	Validation message below the field. Replaces help-text and reddens the border. Property: `errorText`.
`hint`	`string`	`''`	DEPRECATED — renamed to help-text. Still honoured, and warns in the console.
`placeholder`	`string`	`'Search or add...'`	Placeholder shown when no tokens are selected.
`options`	`EsaInputTagOption[]`	`[]`	Optional suggestion list. Set as a property. When provided, a chevron toggles a filtered dropdown.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'md'`	Control size (shared form scale).
`disabled`	`boolean`	`false`	Disables interaction and hides the remove buttons.
`required`	`boolean`	`false`	Blocks submission while no token has been added (valueMissing), and renders an asterisk on the label. A half-typed term that was never committed does not count.
`strict`	`boolean`	`false`
`tags-below`	`boolean`	`false`	Property: `tagsBelow`.
`name`	`string \| undefined`	—	Form field name — the key this control submits under.
`value`	`string[] \| string \| null`	—	Selected tokens. Set/read as a property; mirrored to the form as a comma-joined string. Set as a JS property — there is no attribute.

Events

Event	Type	Default	Description
`change`	`CustomEvent<{ value: string[] }>`	—	Fired whenever tokens are added or removed. Composed and bubbling; detail.value is the current array of token values.

Binding these events from Angular

Every one of these is a CustomEvent, so the payload is on $event.detail — $event.target.value reads empty, with no error. The names are lowercase and Angular passes them to addEventListener verbatim, so camel-casing one means it never fires.

(change)="onChange($event.detail)"