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
andvalue
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.
<o-taginput></o-taginput>
Props
Prop name | Description | Type | Values | Default |
---|---|---|---|---|
allowDuplicates | Allows adding the same item multiple time | boolean | - | From config: taginput: { |
allowNew | Allows adding new items | boolean | - | From config: taginput: { |
ariaCloseLabel | Accessibility label for the close button | string | - | From config: taginput: { |
autocomplete | Native options to use in HTML5 validation | string | - | From config: taginput: { |
checkScroll | Makes the component check if list reached scroll start or end and emit scroll events | boolean | - | From config: taginput: { |
closable | Add close/delete button to the item | boolean | - | From config: taginput: { |
closeIcon | Icon name of close icon on selected item | string | - | From config: taginput: { |
counter | Show counter when maxlength or maxtags props are passed | boolean | - | From config: taginput: { |
createItem | Function to create a new item to push into v-model (items) | ((value: unknown) => unknown) | - | item as T |
customValidity | Custom HTML 5 validation error to set on the form control | string | ((currentValue: unknown[] | null , state: ValidityState) => string) | undefined | - | |
disabled | Same as native input disabled | boolean | - | false |
expanded | Makes input full width when inside a grouped or addon field | boolean | - | false |
filter | Function to filter the options based on the input value - default is label string comparison | ((options: unknown, value: string) => boolean) | - | |
icon | Icon to be shown | string | - | From config: taginput: { |
iconPack | Icon pack to use | string | mdi , fa , fas and any other custom icon pack | From config: taginput: { |
input | The value of the inner input, use v-model:input to make it two-way binding | string | - | "" |
keepFirst | The first option will always be pre-selected (easier to just hit enter or tab) | boolean | - | From config: taginput: { |
keepOpen | Keep open dropdown list after select | boolean | - | From config: taginput: { |
maxitems | Limits the number of items, plus item counter | number | string | - | |
maxlength | Same as native maxlength, plus character counter | number | string | - | |
v-model | The selected items, use v-model to make it two-way binding binding | unknown[] | - | |
openOnFocus | Opens a dropdown with choices when the input field is focused | boolean | - | From config: taginput: { |
options | Taginput options | OptionsPropWithGroups<unknown> | - | |
override | Override existing theme classes completely | boolean | - | |
placeholder | Input placeholder | string | - | |
size | Vertical size of the input control | string | small , medium , large | From config: taginput: { |
teleport | Append 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: { |
useHtml5Validation | Enable HTML 5 native validation | boolean | - | From config: { |
validateItem | Function to validate the value of a new item before it got added | ((value: unknown) => boolean) | - | true |
variant | Color of the each item | string | primary , info , success , warning , danger , and any other custom color | From config: taginput: { |
Events
Event name | Properties | Description |
---|---|---|
scroll-start | the list inside the dropdown reached the start | |
scroll-end | the list inside the dropdown reached it's end | |
icon-click | event Event - native event | on icon click event |
icon-right-click | event Event - native event | on icon right click event |
update:model-value | value string[] | number[] | object[] - updated modelValue prop | modelValue prop two-way binding |
update:input | value string - updated input prop | input prop two-way binding |
input | value string - input valueevent Event - native event | on input change event |
add | value string | number | object - added item | new item got added |
remove | value string | number | object - removed item | item got removed |
focus | event Event - native event | on input focus event |
blur | event Event - native event | on input blur event |
invalid | event Event - native event | on input invalid event |
Slots
Name | Description | Bindings |
---|---|---|
selected | Override selected items | items (string, object)[] - selected itemsoptions object[] - selected options |
header | Define an additional header | |
default | Override the select option | option object - option objectindex number - option indexvalue unknown - option value |
empty | Define content for empty state | |
footer | Define an additional footer | |
counter | Override the counter | items number - items counttotal number - total count |
Class Inspector
Class prop | Description | Props | Suffixes | |
---|---|---|---|---|
rootClass | Class of the root element. | |||
sizeClass | Class of the root element with size. | size | small | |
variantClass | Class of the root element with variant. | variant | primary | |
expandedClass | Class of the root element when expanded. | expanded | ||
containerClass | Class of the inner container element. | |||
itemClass | Class of the tag item element. | |||
closeClass | Class of the tag item close button element. | closable | ||
counterClass | Class of the counter element. | counter | ||
autocompleteClasses | Classes to apply on the internal autocomplete component. More details here. |
Sass variables
Current theme ➜ Oruga
SASS Variable | Default |
---|---|
$taginput-counter-font-size | 0.75em |
$taginput-counter-margin | 0.25rem 0 0 0.5rem |
$taginput-item-background-color | var(--#{$prefix}primary) |
$taginput-item-color | var(--#{$prefix}primary-invert) |
$taginput-item-border-radius | var(--#{$prefix}base-border-radius) |
$taginput-item-margin | 0.275em |
$taginput-item-padding | 0 0.75em 0 0.75em |
$taginput-item-icon-margin | 0.5em |
See ➜ 📄 Full scss file
Current theme ➜ Bulma
SASS Variable | Default |
---|---|
$taginput-height | 100% |
$taginput-tag-size | 0.9em |
See ➜ 📄 Full scss file
Current theme ➜ Bootstrap
SASS Variable | Default |
---|---|
$taginput-badge-bg | $light |
$taginput-badge-color | $dark |
$taginput-badge-font-size | 0.9em |
$taginput-badge-margin | 0.25em |
$taginput-badge-icon-space | 0.25em |
$taginput-counter-margin | 0.25rem 0 0 0.5rem |
$taginput-counter-font-size | 0.75rem |
See ➜ 📄 Full scss file