Tag input – Tsunami

Tags in a form

Labels

Press Enter or comma to add. Backspace removes the last.

<div class="field">
  <label id="ti-label" for="ti-text">Labels</label>
  <div class="tag-input" role="group" aria-labelledby="ti-label" data-name="labels" data-value="design,billing">
    <input type="text" id="ti-text" placeholder="Add a label" />
  </div>
  <small>Press Enter or comma to add. Backspace removes the last.</small>
</div>

A limit, and a change event

No tags yet.

<div class="tag-input" id="ti2" role="group" aria-label="Recipients" data-max="3" data-name="to">
  <input type="text" placeholder="Up to 3 emails" />
</div>
<small id="ti2-out" aria-live="polite">No tags yet.</small>
<script>
  document.getElementById("ti2").addEventListener("tsunami:tagschange", (e) => {
    document.getElementById("ti2-out").textContent = e.detail.value.length + " of 3: " + e.detail.value.join(", ");
  });
</script>

Invalid and disabled

<div class="tag-input" role="group" aria-label="Invalid tags" aria-invalid="true" data-value="not-an-email"></div>
<div class="tag-input" role="group" aria-label="Locked tags" data-value="read,only" data-disabled></div>

Behavior

Enter or comma adds the typed text as a tag. Enter never submits the form from this box.
Backspace in the empty box removes the last tag. The remove button on a tag does the same for that tag.
A paste with commas or new lines is split into tags. A paste of one plain word goes into the box as usual.
Leaving the box with text in it adds that text as a tag.
A tag that is already there is ignored, and nothing is added past data-max.
The text box is added if the markup has none. Add your own when a label needs an id to point at.
The hidden input named by data-name holds the tags joined with commas. A form reset restores the start tags.

API

.tag-input is started on load, and so is one added to the page later.

Methods

Method	Description
`tsunami.tagInput.mount(root?)`	Starts every `.tag-input` inside `root` (default: the document) that is not started yet.
`tsunami.tagInput.value(el)`	The tags as an array of strings.
`tsunami.tagInput.set(el, list)`	Replaces the tags. Duplicates are dropped and `data-max` applies.
`tsunami.tagInput.clear(el)`	Removes every tag.

Events

Event	On	Description
`tsunami:tagschange`	the `.tag-input`, bubbles	Sent when a tag is added or removed. `event.detail.value` is the array of tags.

Keyboard

Key	Description
`Enter` `,`	Adds the typed text as a tag.
`Backspace`	In the empty box, removes the last tag.
`Tab`	Moves from the box to the remove buttons and on.

Attributes

Attribute / element	Values	Description
`.tag-input`	on a `div`	The box. Give it `role="group"` and an `aria-label` or `aria-labelledby`.
`data-value`	comma-separated text	The tags to start with.
`data-max`	a number	The most tags allowed. No limit when left out.
`data-name`	a field name	Adds the hidden input that holds the joined value.
`data-disabled`	present or absent	Disables the text box and hides the remove buttons.
`aria-invalid`	`true`	On `.tag-input`: a red border.