Forms
VeeTagGroup
A selectable tag group that uses the composition API provided by Vee-Validate to perform validation.
Source code
Click to see the source code for this component on GitHub. Feel free to copy it and adjust it for your own use.
Installation
Usage
UiVeeTagGroup wraps UiTagGroup as a choice field: it renders options as selectable tags, adds a label, hint and animated error message, and registers the selection with the surrounding Vee-Validate form. The value is an array of the selected values, or a single value (or undefined) with selection-mode="single". The label names the group for assistive technology and the hint and error message are linked with aria-describedby.
Any other attribute (aria-label, loop, by, ...) is forwarded to UiTagGroup. Tags are not removable here since a form field has a fixed list of options, use UiTagGroup with @remove for that.
Basic example
options takes strings, numbers or { value, label, color, variant, icon, avatar, dot, disabled } objects. The required prop only adds the asterisk and aria-required, so enforce it in your schema.
Default value
Bind a value with v-model (or initialValues on useForm).
Single selection
Use selection-mode="single" for one value. Add disallow-empty-selection when the user has to keep a choice.
Colors
Give every option its own color, icon, avatar or dot. The color, variant, size and shape props of the field are the defaults for all tags.
Variants
soft, solid, outline and modern.
Custom items
The item slot customizes the content of every tag and receives { option, selected, disabled }. Use the default slot to render your own UiTagGroupItems instead of options.
Disabled
Set disabled on the field, or disabled on single options.
Contact support to change your plans.
Some regions are not available yet.
Form
A full form with a single and a multiple selection field.
Props
| Prop | Type | Description |
|---|---|---|
name | string | Field name registered with Vee-Validate. Falls back to a generated id. |
label | string | Label shown above the tags. |
label-hint | string | Extra hint shown next to the label. |
hint | string | Helper text. Hidden while there is an error. |
options | (string | number | { value: any; label?: string; color?: TagGroupColor; variant?: TagGroupVariant; icon?: string; avatar?: string; dot?: boolean; disabled?: boolean })[] | Tags to render. value is stored in the form, label (defaults to the value) is displayed. |
selection-mode | "single" | "multiple" | Whether one or several tags can be selected. Defaults to "multiple". |
disallow-empty-selection | boolean | Prevent the user from deselecting the last selected tag. |
color | TagGroupColor | Default color of the tags. |
variant | "soft" | "solid" | "outline" | "modern" | Default variant of the tags. |
size | "sm" | "md" | "lg" | Default size of the tags. |
shape | "pill" | "rounded" | Default shape of the tags. |
rules | any | Vee-Validate rules (or use a schema on useForm). |
v-model | any | Current value. |
required | boolean | Shows the required asterisk and sets aria-required. |
disabled | boolean | Prevents interaction. |
validate-on-mount | boolean | Validates as soon as the field mounts. |
class | HTMLAttributes["class"] | Classes for the wrapper element. |
Slots
| Slot | Description |
|---|---|
default | Replaces the generated tags. Render your own UiTagGroupItems. |
item | Content of a generated tag. Receives option (including any extra fields you added to it), selected and disabled. |
label | Custom label. Receives error-message and value. |
hint | Custom hint. Receives error-message and value. |
errorMessage | Custom error message. Receives error-message and value. |
Accessibility
The field keeps all the keyboard interactions of UiTagGroup. The label names the group with aria-labelledby, the hint and error message are linked with aria-describedby, and the group is outlined when validation fails. The field is marked as touched once focus leaves the whole group, and like the other Vee components, errors are shown after a value change or on submit.