Forms

TagInput

Free-form token entry field that turns committed text into removable tags while keeping native input, form, and accessibility wiring intact.

import { TagInput } from '@lostgradient/cinder/tag-input';
formtags
01

Overview

Free-form token entry field that turns committed text into removable tags while keeping native input, form, and accessibility wiring intact.

Usage

svelte 
<script lang="ts">
  import FormField from '@lostgradient/cinder/form-field';
  import TagInput from '@lostgradient/cinder/tag-input';
</script>

<FormField
  id="max-tag-input"
  label="Three highlights"
  description="Add up to three short highlights for this release note."
>
  <TagInput max={3} placeholder="Add a highlight…" />
</FormField>

Guidance

For native forms, pass both name and commitOnSubmit when the expected path is "type a tag, click Save." TagInput commits a valid pending draft during the form's submit capture phase, so new FormData(form).getAll(name) includes the same values as the hidden inputs. Invalid, duplicate, or over-limit drafts use the existing inline validation path and block that submit attempt.

Use When

  • Collecting zero or more short free-form values such as labels, emails, or technologies.
  • Letting users review and remove committed values inline before submitting a form.

Avoid When

  • Users must choose from a fixed option list — use combobox instead.
  • The value is a single free-form string rather than a list — use input instead.
Live preview

    Press Enter or comma to turn the current text into a tag.

    02

    When to use

    Use when
    • Collecting zero or more short free-form values such as labels, emails, or technologies.
    • Letting users review and remove committed values inline before submitting a form.
    Avoid when
    • Users must choose from a fixed option list — use combobox instead.
    • The value is a single free-form string rather than a list — use input instead.
    03

    Examples

    Basic tag input

    Commit free-form tags with Enter or a comma delimiter.

    Disabled tag input

    Mirror a locked field that can be read but not changed.

    Maximum tag count

    Cap the number of committed tags and surface an inline message when the limit is reached.

    Pre-populated tags

    Start uncontrolled with existing tags and keep editing in place.

    Read-only tags

    With `readonly`, the committed tags stay visible but cannot be removed and the pending-tag input rejects new entries — distinct from `disabled`, which also dims the whole control.

    Validated email tags

    Keep the value controlled and reject entries that are not email addresses.

    04

    Props

    Props for tag-input
    Name
    Type
    Default
    Description
    id text Stable id for the visible text input. Falls back to FormField context or a generated id.
    value bindable string[] [] Bindable tags.
    delimiter text ',' Key that commits the current input into a tag. Enter always commits separately.
    max number Maximum number of tags allowed. Non-finite values disable the cap.
    validate (tag: string) => booleanstring Optional per-tag validation hook.
    duplicateValuesAllowed boolean false Allow the same trimmed tag value to appear more than once.
    commitOnSubmit boolean false Commit a non-empty pending draft before the parent form submits.
    disabled boolean Disable the input and chip removal affordances.
    readonly boolean false Render the pending-tag input as read-only and make committed tags non-removable.
    name text Hidden input name used for native form submission.
    oninput FormEventHandler<T> | undefined | null
    onkeydown KeyboardEventHandler<T>undefinednull
    onfocus FocusEventHandler<T> | undefined | null
    onblur FocusEventHandler<T> | undefined | null
    onValueChange (tags: string[]) => void Fires whenever a commit or removal requests a new tag list.