TagsField

Component

Props

Usage

modelValue

The field value is always an array of strings.

 <template>
    <TagsField id="skills" v-model="skills" />
</template>

<script setup lang="ts">
const skills = ref<string[]>(['TypeScript', 'Nuxt'])
</script>
 

• Type: string[]
• Default: []

maxTags

Limits how many tags can be added.

 <template>
    <TagsField
        id="technologies"
        v-model="technologies"
        :maxTags="5"
    />
</template>
 

• Type: number

validator

Validates the current tags array and updates v-model:error.

 <template>
    <TagsField
        id="required-tags"
        v-model="tags"
        v-model:error="errorMessage"
        :required="true"
        :validator="validateField"
    />
</template>
 

• Type: function

error (v-model:error)

Binds the field error message for validation feedback.

 <template>
    <TagsField
        id="validated-tags"
        v-model="tags"
        v-model:error="errorMessage"
    />
</template>
 

• Type: string
• Default: ''

disabled

Disables input and tag interactions.

 <template>
    <TagsField id="tags-disabled" v-model="tags" disabled />
</template>
 

• Type: boolean
• Default: false

clearText

Customizes the clear button label.

 <template>
    <TagsField
        id="tags-clear-text"
        v-model="tags"
        clearText="Remove all"
    />
</template>
 

• Type: string
• Default: 'Clear'

required

Marks the field as required when used with a validator.

 <template>
    <TagsField
        id="tags-required"
        v-model="tags"
        :required="true"
        :validator="validateField"
    />
</template>
 

• Type: boolean
• Default: false

showOptionalLabel

When the field is not required, shows an "(optional)" hint next to the label. Set to false to hide it. The hint text defaults to a global setting that can be overridden project-wide, and can also be overridden per field with the optionalLabel prop.

 <template>
    <TagsField label="Keywords" :showOptionalLabel="false" />
</template>
 

• Type: boolean
• Default: true

optionalLabel

Overrides the "(optional)" hint text for this specific field, taking priority over the global default.

 <template>
    <TagsField label="Keywords" optionalLabel="(not required)" />
</template>
 

• Type: string

transparent

When true, removes the default bg-background-container-surface background from the tags input container, making it transparent.

 <template>
    <TagsField transparent />
</template>
 

• Type: boolean
• Default: false

inputClass

Applies additional CSS classes directly to the <input> element, appended last so they can override other classes.

 <template>
    <TagsField inputClass="font-mono" />
</template>
 

• Type: string

helpTextPosition

Sets the position of the help text relative to the field. It uses the Position enum.

 <template>
    <TagsField helpTextPosition="top" helpText="Appears above the field" />
</template>
 

• Type: Position
• Default: Position.BOTTOM

Options

Field behavior

• Press Enter or comma to create one or more tags.
• Pasting comma-separated values creates multiple tags.
• Duplicate values are ignored.
• Click the close icon in a badge to remove that tag.
• If input is empty, Backspace removes the last tag.