Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

TagsInput

Enter, paste, validate, remove, and submit multiple string values in one field.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

VueTypeScript

Install

Run in your project
bunx --bun @getweini/cli@latest add tags-input

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

VueTypeScript
Vue
<script setup lang="ts">
import { ref } from 'vue'
import TagsInput from './components/ui/tags-input/TagsInput.vue'

const skills = ref(['Vue', 'TypeScript'])
</script>

<template>
  <TagsInput
    v-model="skills"
    aria-label="Skills"
    placeholder="Add a skill"
    :max="6"
    class="w-full max-w-xl"
  />
</template>

Press Enter or the separator to add a tag. Paste comma- or newline-separated text to add several values, and use FormData.getAll(name) to read repeated form values.

When to use it

Skills and labels

Capture short, removable strings without building chip behavior.

Recipient entry

Validate each address and cap how many values can be added.

More examples

Validated recipients

Reject invalid drafts and stop at five entries.

Validated recipients
<script setup lang="ts">
import { ref } from 'vue'
import TagsInput from './components/ui/tags-input/TagsInput.vue'

const recipients = ref<string[]>([])
</script>

<template>
  <TagsInput
    v-model="recipients"
    name="recipient"
    placeholder="Add an email address"
    :validate="value => value.includes('@')"
    :max="5"
    aria-label="Recipients"
  />
</template>

Localized controls

Override all built-in text without adding a provider.

Localized controls
<script setup lang="ts">
import { ref } from 'vue'
import TagsInput from './components/ui/tags-input/TagsInput.vue'

const labels = ref(['Urgent'])
</script>

<template>
  <TagsInput
    v-model="labels"
    aria-label="Étiquettes"
    placeholder="Ajouter une étiquette"
    :locale-text="{
      removeTag: value => `Supprimer ${value}`,
      added: value => `${value} ajouté`,
      removed: value => `${value} supprimé`,
    }"
  />
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

TagsInput

Complete API for TagsInput
NameType or signatureDefaultWhat it does
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
placeholderpropstring | undefinedNot setHint shown when no value has been entered or selected.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
maxpropnumber | undefinedNot setLargest allowed value.
separatorpropstring | undefined","Controls the separator behavior of TagsInput.
addOnBlurpropboolean | undefinedtrueControls the add on blur behavior of TagsInput.
allowDuplicatespropboolean | undefinedfalseControls the allow duplicates behavior of TagsInput.
caseSensitivepropboolean | undefinedfalseControls the case sensitive behavior of TagsInput.
validateprop((value: string) => boolean) | undefinedNot setControls the validate behavior of TagsInput.
localeTextpropPartial<TagsInputLocaleText> | undefinedNot setControls the locale text behavior of TagsInput.
modelValuemodelstring[] | undefined[]Current value. Use v-model to keep it in sync with your page.
addevent[value: string]—Emitted when add happens.
update:modelValueevent[value: string[]]—Requests a new model value from the parent.
rejectevent[value: string, reason: TagsInputRejectReason]—Emitted when reject happens.
removeevent[value: string, index: number]—Emitted when remove happens.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
tagslot((props: { value: string; index: number; remove: () => void; }) => unknown) | undefinedOptionalContent for the tag area of TagsInput.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of TagsInput.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
addexposed(value: string) => boolean—Access add from a component template ref.
removeexposed(index: number) => void—Access remove from a component template ref.
clearexposed() => void—Access clear from a component template ref.
Public type definitions
Public types
// packages/frameworks/vue/components/tags-input/types.ts
import type { TagsInputRejectReason } from '@getweini/vue/primitives/tags-input'
import type { ControlSize } from '@getweini/vue/types'

export type { TagsInputRejectReason } from '@getweini/vue/primitives/tags-input'

export interface TagsInputLocaleText {
  removeTag: (value: string) => string
  added: (value: string) => string
  removed: (value: string) => string
}

export interface TagsInputProps {
  id?: string
  name?: string
  form?: string
  placeholder?: string
  disabled?: boolean
  readonly?: boolean
  required?: boolean
  invalid?: boolean
  size?: ControlSize
  max?: number
  separator?: string
  addOnBlur?: boolean
  allowDuplicates?: boolean
  caseSensitive?: boolean
  validate?: (value: string) => boolean
  localeText?: Partial<TagsInputLocaleText>
}

export interface TagsInputRejectEvent {
  value: string
  reason: TagsInputRejectReason
}


// packages/frameworks/vue/dist/vue/primitives/tags-input/index.d.ts
import { type Ref } from 'vue';
export type TagsInputRejectReason = 'duplicate' | 'max' | 'validation';
export interface TagsInputBehaviorProps {
    disabled?: boolean;
    readonly?: boolean;
    max?: number;
    separator?: string;
    addOnBlur?: boolean;
    allowDuplicates?: boolean;
    caseSensitive?: boolean;
    validate?: (value: string) => boolean;
}
export interface TagsInputBehaviorCallbacks {
    onAdd?: (value: string) => void;
    onRemove?: (value: string, index: number) => void;
    onReject?: (value: string, reason: TagsInputRejectReason) => void;
}
export declare function useTagsInputBehavior(props: TagsInputBehaviorProps, model: Ref<string[]>, input: Readonly<Ref<HTMLInputElement | null>>, callbacks?: TagsInputBehaviorCallbacks): {
    tags: import("vue").ComputedRef<string[]>;
    tagRows: import("vue").ComputedRef<{
        tag: string;
        key: string;
    }[]>;
    draft: Ref<string, string>;
    announcement: Ref<string, string>;
    canAdd: import("vue").ComputedRef<boolean>;
    focus: () => void | undefined;
    add: (value: string) => boolean;
    remove: (index: number) => void;
    clear: () => void;
    commitDraft: () => boolean;
    handleInput: (event: Event) => void;
    handleKeydown: (event: KeyboardEvent) => void;
    handlePaste: (event: ClipboardEvent) => void;
    handleBlur: () => void;
};


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • The model is a string array. name produces one hidden form field per value.
  • Use reject(value, reason) to show application-specific feedback for duplicates, validation, or the maximum.

Accessibility and localization

  • Give the input a visible label or accessible name. Removal returns focus to the text field, and status changes are announced politely.

Source contract and editing guidance