Skip to content

Taginput

The Taginput input component allows users to search through a list of options and apply any number of tags. The component is based on the Autocomplete component and supports the W3C ARIA APG Combobox Pattern. Use it with the Field component to access all functionalities.

Examples

Base

Autocomplete

Unlike the dropdown or autocomplete components, the taginput component allows you to enter an arbitrary value (a value taht is not in the list of options). This is useful for creating new tags on the fly. To enable this feature, set the allow-new prop to true.

The options prop can accept several different formats of values:

  • An array of primitives ['A', 'B', 'C']
  • An object literal with key-value pairs { a: 'A', b: 'B', c: 'C' }
  • An array of objects with label and value properties
  • Grouped options by adding additional options to the option object.

Note

The options prop works the same as the Select input component options prop.

Slots

Different parts of the component can be customised using slots.

Limits

The number of entered items can be limited either by the character length of the item using the maxlength prop and by the number of times using the maxitems prop.

Disabled

Prevent inputs with the disabled prop.

Variants

Different styles can be achieved with the variant prop.

Sizes

The component can be displayed in different sizes using the size prop.

Taginput component

A simple tag input field that can have autocomplete functionality.

html
<o-taginput></o-taginput>

Props

Prop nameDescriptionTypeValuesDefault
allowDuplicatesAllows adding the same item multiple timeboolean-
From config:
taginput: {
  allowDuplicates: false
}
allowNewAllows adding new itemsboolean-
From config:
taginput: {
  allowNew: false
}
ariaCloseLabelAccessibility label for the close buttonstring-
From config:
taginput: {
  ariaCloseLabel: "Remove"
}
autocompleteNative options to use in HTML5 validationstring-
From config:
taginput: {
  autocomplete: "off"
}
checkScrollMakes the component check if list reached scroll start or end and emit scroll eventsboolean-
From config:
taginput: {
  checkScroll: false
}
closableAdd close/delete button to the itemboolean-
From config:
taginput: {
  closable: true
}
closeIconIcon name of close icon on selected itemstring-
From config:
taginput: {
  closeIcon: "close"
}
counterShow counter when maxlength or maxtags props are passedboolean-
From config:
taginput: {
  counter: true
}
createItemFunction to create a new item to push into v-model (items)((value: unknown) => unknown)-item as T
customValidityCustom HTML 5 validation error to set on the form controlstring | ((currentValue: unknown[] | null , state: ValidityState) => string) | undefined-
disabledSame as native input disabledboolean-false
expandedMakes input full width when inside a grouped or addon fieldboolean-false
filterFunction to filter the options based on the input value - default is label string comparison((options: unknown, value: string) => boolean)-
iconIcon to be shownstring-
From config:
taginput: {
  icon: undefined
}
iconPackIcon pack to usestringmdi, fa, fas and any other custom icon pack
From config:
taginput: {
  iconPack: undefined
}
inputThe value of the inner input, use v-model:input to make it two-way bindingstring-""
keepFirstThe first option will always be pre-selected (easier to just hit enter or tab)boolean-
From config:
taginput: {
  keepFirst: false
}
keepOpenKeep open dropdown list after selectboolean-
From config:
taginput: {
  keepOpen: false
}
maxitemsLimits the number of items, plus item counternumber | string-
maxlengthSame as native maxlength, plus character counternumber | string-
v-modelThe selected items, use v-model to make it two-way binding bindingunknown[]-
openOnFocusOpens a dropdown with choices when the input field is focusedboolean-
From config:
taginput: {
  openOnFocus: true
}
optionsTaginput optionsOptionsPropWithGroups<unknown>-
overrideOverride existing theme classes completelyboolean-
placeholderInput placeholderstring-
sizeVertical size of the input controlstringsmall, medium, large
From config:
taginput: {
  size: undefined
}
teleportAppend the component to another part of the DOM.
Set true to append the component to the body.
In addition, any CSS selector string or an actual DOM node can be used.
boolean | object | string-
From config:
taginput: {
  teleport: false
}
useHtml5ValidationEnable HTML 5 native validationboolean-
From config:
{
  useHtml5Validation: true
}
validateItemFunction to validate the value of a new item before it got added((value: unknown) => boolean)-true
variantColor of the each itemstringprimary, info, success, warning, danger, and any other custom color
From config:
taginput: {
  variant: undefined
}

Events

Event namePropertiesDescription
scroll-startthe list inside the dropdown reached the start
scroll-endthe list inside the dropdown reached it's end
icon-clickevent Event - native eventon icon click event
icon-right-clickevent Event - native eventon icon right click event
update:model-valuevalue string[] | number[] | object[] - updated modelValue propmodelValue prop two-way binding
update:inputvalue string - updated input propinput prop two-way binding
inputvalue string - input value
event Event - native event
on input change event
addvalue string | number | object - added itemnew item got added
removevalue string | number | object - removed itemitem got removed
focusevent Event - native eventon input focus event
blurevent Event - native eventon input blur event
invalidevent Event - native eventon input invalid event

Slots

NameDescriptionBindings
selectedOverride selected itemsitems (string, object)[] - selected items
options object[] - selected options
headerDefine an additional header
defaultOverride the select optionoption object - option object
index number - option index
value unknown - option value
emptyDefine content for empty state
footerDefine an additional footer
counterOverride the counteritems number - items count
total number - total count

Class Inspector

Classes applied to the element:
Class propDescriptionPropsSuffixes
rootClassClass of the root element.
sizeClassClass of the root element with size.sizesmall
medium
large
variantClassClass of the root element with variant.variantprimary
info
warning
danger
expandedClassClass of the root element when expanded.expanded
containerClassClass of the inner container element.
itemClassClass of the tag item element.
closeClassClass of the tag item close button element.closable
counterClassClass of the counter element.counter
maxitems
autocompleteClassesClasses to apply on the internal autocomplete component. More details here.

Sass variables

Current theme ➜ Oruga

SASS VariableDefault
$taginput-counter-font-size0.75em
$taginput-counter-margin0.25rem 0 0 0.5rem
$taginput-item-background-colorvar(--#{$prefix}primary)
$taginput-item-colorvar(--#{$prefix}primary-invert)
$taginput-item-border-radiusvar(--#{$prefix}base-border-radius)
$taginput-item-margin0.275em
$taginput-item-padding0 0.75em 0 0.75em
$taginput-item-icon-margin0.5em

See ➜ 📄 Full scss file

Current theme ➜ Bulma

SASS VariableDefault
$taginput-height100%
$taginput-tag-size0.9em

See ➜ 📄 Full scss file

Current theme ➜ Bootstrap

SASS VariableDefault
$taginput-badge-bg$light
$taginput-badge-color$dark
$taginput-badge-font-size0.9em
$taginput-badge-margin0.25em
$taginput-badge-icon-space0.25em
$taginput-counter-margin0.25rem 0 0 0.5rem
$taginput-counter-font-size0.75rem

See ➜ 📄 Full scss file

Released under the MIT License.