Tags Input
newWords that got promoted to badges. Type a tag, press Enter, and it turns into a badge. All in one text field.
Open Props in the corner of the example to try variant, size and disabled.
The five text control variants, the same as on Input.
The frame starts at the input's height for its size, from 28px at xs to 48px at xl, and the tags take the badge size that fits: 20px at xs, 24px at sm and md, 28px at lg, 32px at xl. Their radius is concentric with the frame's.
Installation
Usage
<script setup lang="ts">
import { TagsInput, TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInputItemText } from '@/components/ui/tags-input'
const fruits = ref(['Apple', 'Banana'])
</script>
<template>
<TagsInput v-model="fruits">
<TagsInputItem v-for="fruit in fruits" :key="fruit" :value="fruit">
<TagsInputItemText />
<TagsInputItemDelete />
</TagsInputItem>
<TagsInputInput placeholder="Add a fruit" aria-label="Fruits" />
</TagsInput>
</template>
TagsInput: the frame, same as Input; grows as tags wrapTagsInputItem: one per tag, a Badge withTagsInputItemTextandTagsInputItemDeleteTagsInputInput: the text box; attributes likeplaceholdergo here
Enter or a comma turns the text into a tag. Want another separator? Pass a character or a regex to delimiter. Backspace in an empty box selects the last tag; press it again to remove it.
Duplicates and tags over max are refused, and invalid fires. To allow duplicates, turn on duplicate.
Set name, and the tags submit with the form. Give the input an aria-label, or put it in a Field.
Examples
Paste and limits
delimiter takes a regular expression, so a comma, a semicolon or a space all end a tag; addOnPaste splits pasted text on it and addOnBlur keeps what was typed when focus leaves. max caps the count, and invalid reports what was refused.
1 of 5. Comma, space or Enter adds one; paste a list.
Objects
With objects in v-model, convertValue turns the typed text into one and displayValue picks the text to show. A tag takes a badge variant and color of its own.
bug, good-first-issue
In a field
Label, description and error come from the field. The label focuses the text box, required marks it, and invalid turns the frame destructive.
In a form, Enter adds the typed text as a tag and never submits; with nothing typed, it submits the form. Reka UI before 2.11 cancels that Enter a tick late, so TagsInputInput holds the form's submit back itself while there's a draft. To validate the tags with a schema, see VeeValidate.
Press Enter after each one.
API Reference
Every part accepts class, merged over its base classes.
TagsInput
| Prop | Default | Type and description |
|---|---|---|
| modelValue | — | T[] | nullThe tags, bound with |
| defaultValue | — | T[]The starting tags when |
| addOnPaste | — | booleanTurns pasted text into tags, split on |
| addOnTab | — | booleanTurns the typed text into a tag on Tab as well as Enter. |
| addOnBlur | — | booleanTurns the typed text into a tag when the input loses focus. |
| duplicate | — | booleanAllows the same tag twice. Off by default, so a repeat is refused and |
| disabled | — | booleanDisables the input and every tag's button. Also set by a disabled field. |
| delimiter | — | string | RegExpA character or regular expression that turns the typed text into a tag, and splits pasted text with |
| dir | — | DirectionReading direction. In |
| max | — | numberThe most tags allowed. Past it, a new tag is refused and |
| id | — | stringOverrides the |
| convertValue | — | ((value: string) => T)Turns the typed text into the value stored in the model. Required when the tags are objects. |
| displayValue | — | ((value: T) => string)The text shown for a tag. Required when the tags are objects. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the root's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| name | — | stringSubmits the tags with the form under this name, through a hidden input. |
| required | — | booleanMarks the hidden form input required and the text box |
| variant | "outline" | "outline" | "soft" | "filled" | "ghost" | "subtle"The text control look, shared with |
| size | "md" | "xs" | "sm" | "md" | "lg" | "xl"The frame's minimum height, from 28px at |
| Event | Payload and description |
|---|---|
| update:modelValue | [payload: T[]]Fires when a tag is added or removed. |
| invalid | [payload: T]Fires with a tag that was refused, as a duplicate or past |
| addTag | [payload: T]Fires with the tag that was added. |
| removeTag | [payload: T]Fires with the tag that was removed. |
| Slot | Scope and description |
|---|---|
| default | { modelValue: AcceptableInputValue[]; }The |
TagsInputItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableInputValueThe tag this chip stands for, as it appears in the model. |
| disabled | — | booleanKeeps this tag from being removed. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the chip's attributes and classes onto it. |
| as | "span" | AsTag | ComponentThe element or component to render. |
| variant | "soft" | NonNullable<"soft" | "solid" | "subtle" | "outline" | "ghost" | "link" | null | undefined>The badge variant, |
| color | "neutral" | BadgeColor | (string & {})The badge colour, |
| Slot | Scope and description |
|---|---|
| default | {}
|
TagsInputItemText
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the text's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render, a |
| Slot | Scope and description |
|---|---|
| default | {}The text. The tag's |
TagsInputItemDelete
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the button's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render, a |
| Slot | Scope and description |
|---|---|
| default | {}The icon. A cross by default. |
TagsInputInput
| Prop | Default | Type and description |
|---|---|---|
| placeholder | — | stringText shown while nothing is typed. |
| autoFocus | — | booleanFocuses the text box when it mounts. |
| maxLength | — | numberThe most characters one tag may have. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the input's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
Props
- modelValue
T[] | nullThe tags, bound withv-model. Strings, or objects withconvertValueanddisplayValue.- defaultValue
T[]The starting tags whenv-modelis not used.- addOnPaste
booleanTurns pasted text into tags, split ondelimiter.- addOnTab
booleanTurns the typed text into a tag on Tab as well as Enter.- addOnBlur
booleanTurns the typed text into a tag when the input loses focus.- duplicate
booleanAllows the same tag twice. Off by default, so a repeat is refused andinvalidfires.- disabled
booleanDisables the input and every tag's button. Also set by a disabled field.- delimiter
string | RegExpA character or regular expression that turns the typed text into a tag, and splits pasted text withaddOnPaste. A comma by default.- dir
DirectionReading direction. Inrtlthe arrow keys move through the tags the other way.- max
numberThe most tags allowed. Past it, a new tag is refused andinvalidfires.- id
stringOverrides theidtaken from a surrounding field. It lands on the text box, so the field's label focuses it.- convertValue
((value: string) => T)Turns the typed text into the value stored in the model. Required when the tags are objects.- displayValue
((value: T) => string)The text shown for a tag. Required when the tags are objects.- asChild
booleanRender the single child instead of a wrapper, merging the root's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- name
stringSubmits the tags with the form under this name, through a hidden input.- required
booleanMarks the hidden form input required and the text boxaria-required. Also set by a required field.- variant
"outline" "outline" | "soft" | "filled" | "ghost" | "subtle"The text control look, shared withInput:outline,soft,filled,ghostorsubtle.- size
"md" "xs" | "sm" | "md" | "lg" | "xl"The frame's minimum height, from 28px atxsto 48px atxl; the tags and type scale with it.
Emits
- update:modelValue
[payload: T[]]Fires when a tag is added or removed.- invalid
[payload: T]Fires with a tag that was refused, as a duplicate or pastmax.- addTag
[payload: T]Fires with the tag that was added.- removeTag
[payload: T]Fires with the tag that was removed.
Slots
- default
{ modelValue: AcceptableInputValue[]; }TheTagsInputItems, one per tag, and theTagsInputInput. ReceivesmodelValue.
Props
- value*
AcceptableInputValueThe tag this chip stands for, as it appears in the model.- disabled
booleanKeeps this tag from being removed.- asChild
booleanRender the single child instead of a wrapper, merging the chip's attributes and classes onto it.- as
"span" AsTag | ComponentThe element or component to render.- variant
"soft" NonNullable<"soft" | "solid" | "subtle" | "outline" | "ghost" | "link" | null | undefined>The badge variant,softby default.- color
"neutral" BadgeColor | (string & {})The badge colour,neutralby default.
Slots
- default
{}TagsInputItemTextandTagsInputItemDelete.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the text's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render, aspanby default.
Slots
- default
{}The text. The tag'sdisplayValueby default.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the button's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render, abuttonby default.
Slots
- default
{}The icon. A cross by default.
Props
- placeholder
stringText shown while nothing is typed.- autoFocus
booleanFocuses the text box when it mounts.- maxLength
numberThe most characters one tag may have.- asChild
booleanRender the single child instead of a wrapper, merging the input's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| tags-input | data-variant, data-size, data-disabled, data-focused, data-invalid | The frame, holding the hidden form input. data-invalid while a refused tag is still in the text box. |
| tags-input-item | data-variant, data-color, data-state, data-disabled | One tag, a badge. data-state="active" while selected from the keyboard. |
| tags-input-item-text | — | The tag's text, which labels its delete button. |
| tags-input-item-delete | data-state, data-disabled | The button that removes the tag, out of the tab order. |
| tags-input-input | data-invalid, aria-invalid | The text box. |
CSS variables
| Variable | Default | Description |
|---|---|---|
| --frame-radius | --radius-control-md at md | The frame's radius for its size. Tags take this less their distance from the edge, but never less than half of it. Set --control-radius to change every control at once. |
| --control-padding | 12px | Where the text starts from the frame's edge while there are no tags, as in Input. |
| --tags-inset | 6px | The tags' distance from the frame's outer edge, per size. |
Keyboard
| Key | Action |
|---|---|
| Enter | Turns the typed text into a tag. Tab does too with addOnTab. |
| Backspace | In an empty text box, selects the last tag; pressed again, removes it. |
| ArrowLeft / ArrowRight | Moves the selection through the tags, and back to the text box past the last one. |
| Home / End | Selects the first or last tag. |
| Delete | Removes the selected tag. |