Tag Input <mv-tag-input>

When to use

• A form collects several free-form values such as tags, keywords, skills or email recipients and must submit them
• Users paste lists from a spreadsheet, an email client or a document and expect each entry to become a tag
• Entries must match a format such as email addresses, with invalid ones kept and flagged rather than dropped
• A filter bar or settings page needs removable keyword chips that work fully from the keyboard

Avoid when

• Values must be picked from a long or remote list with filtering, groups and option rendering → use Combobox instead
• The field is a storefront search with recent searches and product results → use Search Autocomplete instead
• Only a fixed handful of options can be chosen, with nothing typed → use Checkbox instead

node scripts/add.mjs tag-input --out ./src/marvelous

<mv-tag-input name="tags" value="design, research"></mv-tag-input>

<form id="mv-tag-input-demo" style="display:grid;gap:1.1rem;width:min(100%,34rem);padding:1.25rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-xl);background:var(--mv-surface);box-shadow:var(--mv-shadow-sm)">
  <div style="display:grid;gap:.4rem">
    <label for="mv-tag-demo-topics" style="font-size:.875rem;font-weight:600">Topics</label>
    <mv-tag-input id="mv-tag-demo-topics" name="topics" value="design, research" unique max="6" required placeholder="Add a topic…">
      <datalist>
        <option value="Accessibility"></option>
        <option value="Branding"></option>
        <option value="Café culture"></option>
        <option value="Localization"></option>
        <option value="Pricing"></option>
        <option value="Typography"></option>
      </datalist>
    </mv-tag-input>
    <small style="color:var(--mv-fg-muted);font-size:.8125rem">Up to 6. Paste “ux, pricing; Café culture” to add several; typing “Design” flashes the existing tag.</small>
  </div>

  <div style="display:grid;gap:.4rem">
    <label for="mv-tag-demo-invite" style="font-size:.875rem;font-weight:600">Invite reviewers</label>
    <mv-tag-input id="mv-tag-demo-invite" name="reviewers" separator=";" unique pattern="[^\s@]+@[^\s@]+\.[^\s@]{2,}" placeholder="[email protected]"
      value="[email protected]; [email protected]; lucia.fernandez@lumen"></mv-tag-input>
    <small style="color:var(--mv-fg-muted);font-size:.8125rem">Emails only, sent as one “;”-separated value. Invalid addresses stay, flagged, so nothing is lost.</small>
  </div>

  <div style="display:flex;flex-wrap:wrap;align-items:center;gap:.5rem">
    <button class="mv-button" type="submit">Save project</button>
    <button class="mv-button" data-variant="ghost" type="reset">Reset</button>
    <output id="mv-tag-demo-out" style="flex-basis:100%;min-height:1.2em;font:.75rem/1.5 var(--mv-font-mono);color:var(--mv-fg-muted);overflow-wrap:anywhere"></output>
  </div>
</form>

<script type="module">
  const form = document.getElementById("mv-tag-input-demo");
  const out = document.getElementById("mv-tag-demo-out");
  form.addEventListener("submit", (e) => {
    e.preventDefault();
    const fd = new FormData(form);
    out.textContent = [...fd].map(([k, v]) => `${k}=${v}`).join("  ·  ");
  });
  form.addEventListener("invalid", () => { out.textContent = ""; }, true);
</script>

API

Attributes

Properties

Methods

Events

Content structure

CSS classes

CSS variables

Accessibility

The host is a form-associated custom element: a <label for> names it (the inner text field is aria-labelledby the label, or takes the host’s aria-label), clicking the label or the empty part of the box focuses the field, and validity messages anchor to the field. Chips are a real list (ul role=list), so screen readers hear “list, 2 items”; each chip has a real button named “Remove design” (the × icon is aria-hidden). Only the text field is in the Tab order: Left arrow at the start of the field, or Backspace in an empty field, moves focus to the last chip’s remove button; Left/Right (mirrored in RTL), Home and End walk the chips, Right past the last one returns to the field; Backspace removes and moves left, Delete and Enter remove and stay in place, Escape or typing a character goes back to the field. A short screen-reader hint on the field says Enter or comma adds and Left arrow reaches the tags. One polite status region announces only results, briefly: “design added”, “3 tags added”, “research removed, 2 tags”, “Design is already added”, “Limit reached: 6 tags”. Invalid chips are flagged by a “!” mark, a wavy underline and the text “(invalid)”, not by color alone, and the field gets aria-invalid. Focus is always visible (the whole chip is outlined when its button has focus); forced colors use system outlines, a dashed border for invalid chips and a CanvasText mark. Chip entry and the duplicate flash scale only with --mv-motion and stop under prefers-reduced-motion or [data-motion=reduce] (the highlight still shows, statically). Enter never submits while text is pending; with an empty field it submits the form as usual. IME composition is respected.