Tags Input

TagsInput converts text into removable values. It supports keyboard navigation, batch paste, duplicate rules, object values, and native forms.

Use Combobox when values must come from suggestions.

Anatomy

• #tag: Replaces an entire tag, with value, label, highlight state, and remove action.
• #delete: Content inside each default remove button.
• #input: Replaces the text input. Bind inputProps to preserve behavior and accessibility.
• #clear: Content inside the optional clear-all button.

The component generates tag wrappers, remove controls, an editable input, and hidden native form controls. Style those generated parts with the matching ui keys.

Usage

<script setup lang="ts">
import { TagsInput } from "akaza-ui";
import { ref } from "vue";

const tags = ref(["Vue", "TypeScript"]);
</script>

<template>
  <TagsInput v-model="tags" placeholder="Add technology" clearable />
</template>

Examples

Delimiters and blur

Enter always adds the current text. A one-character string delimiter also adds on that key. Set addOnBlur or addOnTab for data-entry workflows that need those commit points.

<template>
  <TagsInput
    v-model="keywords"
    delimiter=","
    add-on-blur
    add-on-tab
    placeholder="Add keyword"
  />
</template>

Batch paste

Set addOnPaste to split clipboard text using delimiter. Duplicate, invalid, and over-limit values emit invalid-value; accepted values commit in one model update.

<template>
  <TagsInput
    v-model="recipients"
    add-on-paste
    :delimiter="/[;,]/"
    placeholder="Paste email addresses"
  />
</template>

Validation and limits

validate receives the converted value. max makes the input read-only after the limit and reports additional values with reason max.

<script setup lang="ts">
const isEmail = (value: unknown) =>
  typeof value === "string" && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
</script>

<template>
  <TagsInput
    v-model="recipients"
    :validate="isEmail"
    :max="5"
    @invalid-value="(value, details) => showError(value, details.reason)"
  />
</template>

Number and object values

Use convertValue to produce non-string models. Pair object values with displayValue, serializeValue, and isEqual so rendering, forms, and duplicate checks use stable identities.

<template>
  <TagsInput
    v-model="users"
    name="user"
    :convert-value="name => ({ id: findId(name), name })"
    :display-value="user => user.name"
    :serialize-value="user => String(user.id)"
    :is-equal="(a, b) => a.id === b.id"
  />
</template>

Custom tag and input

Use #tag for the complete token or #delete for only the remove icon. A custom #input must bind inputProps.

<template>
  <TagsInput v-model="tags">
    <template #tag="{ label, remove, isHighlighted }">
      <span :data-active="isHighlighted || undefined">
        {{ label }}
        <button type="button" @click="remove">Remove</button>
      </span>
    </template>
    <template #input="{ inputProps }">
      <input v-bind="inputProps" aria-label="Add another tag">
    </template>
  </TagsInput>
</template>

Field integration

Inside Field, TagsInput inherits id, name, required/disabled/invalid state, and description/error IDs. A required field is invalid only after interaction or invalid submit.

<template>
  <Field label="Project labels" name="labels" required>
    <TagsInput v-model="labels" placeholder="Add label" />
  </Field>
</template>

Cancel changes

add, remove, value-change, and input-change are cancelable. Cancel the earliest relevant event to stop the operation.

<template>
  <TagsInput
    v-model="tags"
    @remove="(value, details) => value === 'required' && details.cancel()"
  />
</template>

Native Form Reset

A native form reset restores the initial model and clears interaction state. Calling preventDefault() on the reset event preserves the current value. Reset updates v-model without emitting value-change.

API Reference

Models

Props

Emits

Slots

Exposed Methods

UI Options

Styling Hooks

Root data-akaza-state is empty or filled. Plain class applies to the root editor. Use ui.item, ui.input, and ui.delete for internal parts.

Keyboard