Prototype Library

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, hint text, and disabled state are attribute-driven. Disabled fields keep their chips but drop the remove buttons.

<esa-input-tag label="Required" required placeholder="At least one tag"></esa-input-tag>
<esa-input-tag label="With hint" hint="Press Enter to add each 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

PropTypeDefaultDescription
label string '' Visible label rendered above the field.
hint string '' Helper text shown below the field.
placeholder string 'Search or add...' Placeholder shown when no tokens are selected.
options { value, label }[] [] Optional suggestion list. Set as a property. When provided, a chevron toggles a filtered dropdown.
value string[] [] Selected tokens. Set/read as a property; mirrored to the form as a comma-joined string.
size 'xs' | 'sm' | 'md' | 'lg' 'md' Control size (shared form scale).
required boolean false Marks the field required and renders an asterisk on the label.
disabled boolean false Disables interaction and hides the remove buttons.
name string '' Form field name used when the element participates in a form.

Events

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

Accessibility

  • The text field carries role="combobox" with aria-expanded, aria-haspopup="listbox", and aria-autocomplete="list".
  • The dropdown is role="listbox"; each suggestion and the "Add" row are role="option" with aria-selected.
  • Keyboard: Enter adds the typed value or the highlighted suggestion, ArrowUp/ArrowDown move through suggestions, Backspace on an empty field removes the last token, Escape closes the dropdown.
  • Each chip's remove button has an aria-label naming the token it removes; outside-click closes the dropdown.
  • Form-associated via ElementInternals — values submit with the enclosing form.

Tokens

Override the form token layer to re-skin without touching the component:

  • --form-bg · --form-text-color · --form-border-color / --form-border-color-hover / --form-border-color-focus
  • --form-{height,padding-x,padding-y,font-size,radius}-{xs,sm,md,lg} (size scale)
  • --form-label-color · --form-help-color · --form-placeholder-color · --form-bg-disabled
  • --color-active-overlay · --color-primary (chips) · --color-surface · --color-surface-sunken (dropdown)
  • --focus-ring-width / --focus-ring-color · --z-dropdown · --shadow-200 · --radius-full