Tags Input

A component for adding and managing a list of tags or keywords, often with autocomplete and removal features.

Label

Anatomy

Usage

<script>
  import {TagsInput} from 'ui-ingredients';
  import {XCloseIcon} from '$lib/icons';
</script>

<TagsInput.Root>
  {#snippet children(context)}
    <TagsInput.Label>Label</TagsInput.Label>

    <TagsInput.Control>
      {#each context.value as value, index}
        <TagsInput.Item {index} {value}>
          <TagsInput.ItemPreview>
            <TagsInput.ItemText>{value}</TagsInput.ItemText>
            <TagsInput.ItemDeleteTrigger>
              <XCloseIcon />
            </TagsInput.ItemDeleteTrigger>
          </TagsInput.ItemPreview>
          <TagsInput.ItemInput />
        </TagsInput.Item>
      {/each}
    </TagsInput.Control>
    <TagsInput.Input />
    <TagsInput.ClearTrigger>Clear</TagsInput.ClearTrigger>
    <TagsInput.HiddenInput />
  {/snippet}
</TagsInput.Root>

Usage with Field component

<script>
  import {TagsInput, Field} from 'ui-ingredients';
  import {XCloseIcon} from '$lib/icons';
</script>

<Field.Root>
  <TagsInput.Root>
    {#snippet children(context)}
      <TagsInput.Label>Label</TagsInput.Label>

      <TagsInput.Control>
        {#each context.value as value, index}
          <TagsInput.Item {index} {value}>
            <TagsInput.ItemPreview>
              <TagsInput.ItemText>{value}</TagsInput.ItemText>
              <TagsInput.ItemDeleteTrigger>
                <XCloseIcon />
              </TagsInput.ItemDeleteTrigger>
            </TagsInput.ItemPreview>
            <TagsInput.ItemInput />
          </TagsInput.Item>
        {/each}
      </TagsInput.Control>
      <TagsInput.Input />
      <TagsInput.ClearTrigger>Clear</TagsInput.ClearTrigger>
      <TagsInput.HiddenInput />
    {/snippet}
  </TagsInput.Root>

  <Field.HelperText>This is a helper text</Field.HelperText>
  <Field.ErrorText>This is an error text</Field.ErrorText>
</Field.Root>

API Reference

Root

Prop	Default	Description
`addOnPaste`	`false`	`boolean` Whether to add a tag when you paste values into the tag input
`allowOverflow`		`boolean` Whether to allow tags to exceed max. In this case, we'll attach `data-invalid` to the root
`autoFocus`		`boolean` Whether the input should be auto-focused
`blurBehavior`		`"clear" \| "add"` The behavior of the tags input when the input is blurred - `"add"`: add the input value as a new tag - `"clear"`: clear the input value
`defaultInputValue`		`string` The initial tag input value when rendered. Use when you don't need to control the tag input value.
`defaultValue`		`string[]` The initial tag value when rendered. Use when you don't need to control the tag value.
`delimiter`	`","`	`string \| RegExp` The character that serves has: - event key to trigger the addition of a new tag - character used to split tags when pasting into the input
`disabled`		`boolean` Whether the tags input should be disabled
`editable`	`true`	`boolean` Whether a tag can be edited after creation, by pressing `Enter` or double clicking.
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`{ root?: string; input?: string; hiddenInput?: string; clearTrigger?: string; label?: string; control?: string; item(opts: ItemProps)?: string; }` The ids of the elements in the tags input. Useful for composition.
`inputValue`		`string` The controlled tag input's value
`invalid`		`boolean` Whether the tags input is invalid
`max`	`Infinity`	`number` The max number of tags
`maxLength`		`number` The max length of the input.
`name`		`string` The name attribute for the input. Useful for form submissions
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onHighlightChange`		`(details: HighlightChangeDetails) => void` Callback fired when a tag is highlighted by pointer or keyboard navigation
`onInputValueChange`		`(details: InputValueChangeDetails) => void` Callback fired when the input value is updated
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onValueChange`		`(details: ValueChangeDetails) => void` Callback fired when the tag values is updated
`onValueInvalid`		`(details: ValidityChangeDetails) => void` Callback fired when the max tag count is reached or the `validateTag` function returns `false`
`readOnly`		`boolean` Whether the tags input should be read-only
`required`		`boolean` Whether the tags input is required
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`validate`		`(details: ValidateArgs) => boolean` Returns a boolean that determines whether a tag can be added. Useful for preventing duplicates or invalid tag values.
`value`		`string[]` The controlled tag value
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-empty`
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-part`	root
`data-readonly`	Present when read-only
`data-scope`	tags-input

ClearTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	clear-trigger
`data-readonly`	Present when read-only
`data-scope`	tags-input

Control

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-part`	control
`data-readonly`	Present when read-only
`data-scope`	tags-input

HiddenInput

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Input

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-invalid`	Present when invalid
`data-part`	input
`data-readonly`	Present when read-only
`data-scope`	tags-input

Item

Prop	Default	Description
`disabled`		`boolean` Whether the item is disabled.
`index`		`string \| number`
`value`		`string`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	item
`data-scope`	tags-input
`data-value`	The value of the item

ItemDeleteTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

ItemInput

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

ItemPreview

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-highlighted`	Present when highlighted
`data-part`	item-preview
`data-scope`	tags-input
`data-value`	The value of the item

ItemText

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-highlighted`	Present when highlighted
`data-part`	item-text
`data-scope`	tags-input

Label

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-part`	label
`data-readonly`	Present when read-only
`data-scope`	tags-input

Accessibility

Keyboard Support

Key	Description
ArrowLeft	Moves focus to the previous tag item
ArrowRight	Moves focus to the next tag item
Backspace	Deletes the tag item that has visual focus or the last tag item
Enter	When a tag item has visual focus, it puts the tag in edit mode. When the input has focus, it adds the value to the list of tags
Delete	Deletes the tag item that has visual focus
Control + V	When `addOnPaste` is set. Adds the pasted value as a tags