Mielui · Tag Input

Installation

pnpm dlx @mielui/svelte add tag-input

Usage

Disabled Tag Input fields omit their hidden values from native form submission. Keyboard composition does not commit tags. Native input callbacks run before internal handling and can cancel it with preventDefault. External description IDs from Root and Input are merged without duplicates. Only the rendered description or error is linked; an error replaces the built-in description until it clears.

Bind tags for the tag list. Compose List for the tokens and Input for entry inside Root .

import * as TagInput from '$lib/mielui/components/tag-input';

let tags = $state(['svelte']);

<TagInput.Root bind:tags label="Topics">
  <TagInput.List />
  <TagInput.Input placeholder="Add a topic…" />
</TagInput.Root>

Examples

Responding to changes

onAdd and onRemove report single-tag edits; onTagsChange reports the whole list.

Validation

Return false or an error message from validate to reject a tag. Rejections arrive through onReject with a human-readable reason.

Limiting tags

max caps the list. Extra tags are rejected with a max-tags reason.

API reference

TagInput.Root

Owns tags and draft entry state.

Prop	Type	Default
`tags` Bindable	`string[] \| undefined`	`[]`
`query` Bindable	`string \| undefined`	`''`
`max`	`number \| undefined`	`—`
`allowDuplicates`	`boolean \| undefined`	`false`
`disabled`	`boolean \| undefined`	`false`
`label`	`string \| undefined`	`—`
`description`	`string \| undefined`	`—`
`error`	`string \| undefined`	`—`
`name`	`string \| undefined`	`—`
`required`	`boolean \| undefined` Requires at least one tag for native form submission. Carried by a dedicated validation anchor, since hidden inputs are barred from constraint validation.	`false`
`requiredMessage`	`string \| undefined` Validation message shown when `required` is set and no tags are added.	`'Add at least one tag.'`
`variant`	`TagInputVariant \| undefined`	`'outline'`
`validate`	`((tag: string) => string \| boolean) \| undefined`	`—`
`normalize`	`((tag: string) => string) \| undefined`	`—`
`delimiters`	`string[] \| undefined`	`[',']`
`addOnBlur`	`boolean \| undefined`	`true`
`addOnPaste`	`boolean \| undefined`	`true`
`onTagsChange`	`((tags: string[]) => void) \| undefined`	`—`
`onAdd`	`((tag: string) => void) \| undefined`	`—`
`onRemove`	`((tag: string) => void) \| undefined`	`—`
`onReject`	`((rejection: TagInputRejection) => void) \| undefined`	`—`
`id`	`string \| undefined`	`—`
`class`	`string \| undefined`	`—`
`children`	`Snippet<[]> \| undefined`	`—`

TagInput.Input

Accepts new tag text.

Prop	Type	Default
`placeholder`	`string \| undefined`	`'Add a tag…'`
`element` Bindable	`HTMLInputElement \| undefined`	`undefined`
`class`	`string \| undefined`	`—`

TagInput.List

Groups the entered tags.

Prop	Type	Default
`label`	`string \| undefined`	`'Tags'`
`class`	`string \| undefined`	`—`
`children`	`Snippet<[]> \| undefined`	`—`

TagInput.Tag

Renders one tag with its remove control.

Prop	Type	Default
`value` Required	`string`	`—`
`index`	`number \| undefined`	`—`
`removable`	`boolean \| undefined`	`true`
`onRemove`	`((tag: string) => void) \| undefined`	`—`
`class`	`string \| undefined`	`—`
`children`	`Snippet<[]> \| undefined`	`—`