MultiselectElement
Renders a multiselect input.
Basic Usage
<MultiselectElement>
component can be used in a <Vueform>
component:
<template>
<Vueform>
<MultiselectElement
name="multiselect"
:native="false"
:items="[
'Vue.js',
'React',
'AngularJS',
]"
/>
</Vueform>
</template>
Configuration options can be passed over as regular component props. Check out Options section for available configuration options.
Options
Find below the list of options that can use to configure MultiselectElement
component. Options can be passed to the component via props in inline templates, or in the element's object when using schema
.
native
- Type:
boolean
- Default:
true
<MultiselectElement :native="true" ... />
<MultiselectElement :native="false" ... />
Whether the native HTML select input should be used. Automatically becomes false
if search
is true
.
items
- Type:
object|array|function|string
- Default:
{}
- Localizable:
true
Defines the option list.
Array
Can be a plain array
where both the option value and label will be the same:
<MultiselectElement :native="false" :items="['Vue.js', 'React', 'AngularJS']" ... />
Object
Can be an plain object
where the object key is the value and the value is the label of the option:
<MultiselectElement :native="false" :items="{
vuejs: 'Vue.js',
react: 'React',
angularjs: 'AngularJS'
}" ... />
When options are defined as objects
they can contain a disabled
property that will disable the option:
<MultiselectElement :native="false" :items="[
{ value: 'vuejs', label: 'Vue.js' },
{ value: 'react', label: 'React', disabled: true },
{ value: 'angularjs', label: 'AngularJS', disabled: true },
]" ... />
Array of Objects
Can be an array
of objects. Each item should be an object that contains at least a valueProp
and a labelProp
('value'
and 'label'
by default):
<MultiselectElement :native="false" :items="[
{ value: 'vuejs', label: 'Vue.js' },
{ value: 'react', label: 'React' },
{ value: 'angularjs', label: 'AngularJS' },
]" ... />
Async
Can be an async function
or a function that returns a Promise
. The functions receives query
as its first param, which is the search query when search
is enabled and delay
is > -1
. The resolved value should have one of the formats from above.
<MultiselectElement :native="false" :items="async function(query, input){
let el$ = input.$parent.el$ // the element's component
let other_element = el$.form$.el$('other_element') // an other element
return await (axios.get('https://vueform.com/json/async-items.json')).data
}" ... />
If native: false
is used the first param the callback receives is the search query (if search
is enabled) while the second is the input
. The SelectElement
component instance can be accessed via input.$parent.el$
.
<MultiselectElement :native="true" :items="async function(el$){
return await (axios.get('https://vueform.com/json/async-items.json')).data
}" ... />
If native: true
is used the only param the callback will receive is the el$
which is the SelectElement
component instance.
String (endpoint)
Can be a string
that is an endpoint where the options should be loaded from. The endpoint should return any of the formats from above. If search
and delay
is > -1
the endpoint will receive a query
param which contains the search query.
<MultiselectElement :native="false" items="https://vueform.com/json/async-items.json" ... />
Can be a string
that contains variables in {elementPath|'default'}
format. This way we can achieve chained selects or dependent select options..
<MultiselectElement name="category" items="https://api.vueform.com/categories" ... />
<MultiselectElement name="subcategory" items="https://api.vueform.com/category/{category|'0'}" ... />
The items that depend on an other element's value, will be refetched when the other element's value change. We can also reference complex elements (eg. lists or objects), in which case their value will be transformed to JSON and added to the url in an encoded format. If a value is already selected which is not among the newly fetched items, the value will be removed.
Hint: option template can be overridden with
#option
slot and selected options label with#multiple-label
.
labelProp
- Type:
string
- Default:
label
- Native support:
false
<MultiselectElement label-prop="name" ... />
The name of the object property that contains the option label when items
is an array of objects.
valueProp
- Type:
string
- Default:
value
- Native support:
false
<MultiselectElement value-prop="id" ... />
The name of the object property that contains the option value when items
is an array of objects.
dataKey
- Type:
string
- Default:
undefined
<MultiselectElement data-key="options" ... />
The name of the property that contains the options when using endpoint items. Can be a path string with dot .
syntax, eg: data.options
. If not defined the endpoint should return the options directly.
Eg. endpoint response without dataKey
:
[
{ label: 'Vue.js', value: 'vuejs' },
{ label: 'React', value: 'react' },
{ label: 'AngularJS', value: 'angularjs' },
]
Eg. endpoint response with dataKey: "options"
:
{
options: [
{ label: 'Vue.js', value: 'vuejs' },
{ label: 'React', value: 'react' },
{ label: 'AngularJS', value: 'angularjs' },
],
// ...
}
searchParam
- Type:
string
- Default:
query
<MultiselectElement search-param="search" ... />
The name of the search param sent as a GET param when using endpoint items, search: true
and delay > -1
.
search
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :search="true" ... />
Enables searching among options. If true
non-native select will be used.
If items
are provided as a plain array
that contains strings, the string values will be searched. When items
is an array of objects, the object's trackBy
property will be searched.
trackBy
- Type:
string|array
- Default:
label
- Native support:
false
<MultiselectElement :track-by="['name', 'email']" ... />
The name of the object properties that contains the text that should be searched when search
is true
and items
is an array of objects. Can also be a simple string.
strict
- Type:
boolean
- Default:
true
- Native support:
false
<MultiselectElement :strict="true" />
<MultiselectElement :strict="false" />
Whether the search should respect accents/diacritics.
multipleLabel
- Type:
function
- Default:
undefined
- Native support:
false
<MultiselectElement :multiple-label="values => `${values.length} selected`" ... />
A function
that returns the label of the multiselect based on the number of options selected. By default it returns local.multiselect.multipleLabelOne
and local.multiselect.multipleLabelMore
labels.
multipleLabelSingle
- Type:
string
- Default:
locale.vueform.multiselect.multipleLabelOne
- Native support:
false
<MultiselectElement multiple-label-single="1 selected" ... />
Defines the select label's text as a string when only one option is selected.
Can be used instead of multipleLabel
function.
multipleLabelMultiple
- Type:
string
- Default:
locale.vueform.multiselect.multipleLabelMore
- Native support:
false
<MultiselectElement multiple-label-multiple=":x: selected" ... />
Defines the select label's text as a string when there more options are selected. The :x:
is a variable representing the number of selected options.
Can be used instead of multipleLabel
function.
create
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :create="true" ... />
Whether the user can create new options. This will automatically enable search
.
appendNewOption
- Type:
boolean
- Default:
true
- Native support:
false
<MultiselectElement :create="true" :append-new-option="true" ... />
<MultiselectElement :create="true" :append-new-option="false" ... />
Whether the new option should be appended to the option list when create
is enabled.
addOptionOn
- Type:
array
- Default:
["enter"]
- Native support:
false
<MultiselectElement :create="true" :add-option-on="['enter', 'space', 'tab', ';', ',']" />
Defines on which key a new option should be added when create
is true
. Possible values:
enter
space
tab
;
,
allowAbsent
- Type:
boolean
- Default:
false
- Native support:
false
<template>
<Vueform ref="form$">
<MultiselectElement name="multiselect" :items="[1,2]" allow-absent />
</Vueform>
</template>
<script setup>
import { ref, onMounted } from 'vue'
const form$ = ref(null)
onMounted(() => {
form$.value.update({
multiselect: 3
})
})
</script>
Whether to allow values to be set programmatically that are not among the items
.
object
- Type:
boolean
- Default:
false
- Native support:
false
<!-- With `object: false` -->
<MultiselectElement name="object_false" :native="false" :object="false" :items="[
{ label: 'Vue.js', value: 'vuejs' },
{ label: 'React', value: 'react' },
{ label: 'AngularJS', value: 'angularjs' },
]" ... />
<!-- With `object: true` -->
<MultiselectElement name="object_true" :native="false" :object="true" :items="[
{ label: 'Vue.js', value: 'vuejs' },
{ label: 'React', value: 'react' },
{ label: 'AngularJS', value: 'angularjs' },
]" ... />
Whether the value should contain the full option object.
limit
- Type:
number
- Default:
-1
- Native support:
false
<MultiselectElement :limit="2" :items="['Vue.js', 'React', 'AngularJS']" ... />
Limits the number of options to be displayed. The -1
value turns off the limit.
max
- Type:
number
- Default:
-1
- Native support:
false
<MultiselectElement :max="2" ... />
Limits the maximum number of options that can be selected.
groups
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :groups="true" :items="[
{
label: 'Vue.js packages',
items: ['Vue Router', 'Vuex', 'Vue CLI']
},
{
label: 'React packages',
items: ['React Router', 'Redux', 'Create React App']
},
{
label: 'AngularJS packages',
items: ['Ngrx/Store'],
disabled: true,
},
]" ... />
Enables option groups.
When groups
is true
the items
must be provided in the following format:
[
{
[groupLabel]: 'Group label',
[groupOptions]: items,
disabled: Boolean,
},
//...
]
groupLabel
defines the key for the group labelgroupOptions
defines the key for the group optionsitems
are the list of options as you would regularly define without groupsdisabled
determines whether the group should be disabled (optional)
groupLabel
- Type:
string
- Default:
label
- Native support:
false
<MultiselectElement group-label="name" ... />
The name of the object property that contains the group label when using groups
.
groupOptions
- Type:
string
- Default:
items
- Native support:
false
<MultiselectElement group-options="options" ... />
The name of the object property that contains the group items when using groups
.
groupHideEmpty
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :group-hide-empty="true" ... />
Whether groups that have no items should be hidden.
groupSelect
- Type:
boolean
- Default:
true
- Native support:
false
<MultiselectElement :group-select="true" ... />
<MultiselectElement :group-select="false" ... />
Whether group labels should be selectable when using groups
. When enabled and a group label is selected all its enabled options get selected/deselected.
openDirection
- Type:
string
- Default:
bottom
- Native support:
false
<MultiselectElement open-direction="top" />
<MultiselectElement open-direction="bottom" />
Whether the option list should appear on 'top'
or 'bottom'
. When displayed on 'top'
the options are reversed.
appendToBody
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :append-to-body="true" ... />
Whether the dropdown list should be appended to <body>
and positioned absolutely.
appendTo
- Type:
string
- Default:
undefined
- Native support:
false
<MultiselectElement append-to="#my-div" ... />
Can be used instead of appendToBody
to teleport the dropdown to a specific DOM. The value should be a query selector.
canClear
- Type:
boolean
- Default:
true
- Native support:
false
<MultiselectElement :can-clear="true" />
<MultiselectElement :can-clear="false" />
Whether selected options can be cleared.
clearOnSelect
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :clear-on-select="true" :search="true" ... />
<MultiselectElement :clear-on-select="false" :search="true" ... />
Whether search query should be cleared when an option is selected.
closeOnSelect
- Type:
boolean
- Default:
true
- Native support:
false
<MultiselectElement :close-on-select="true" />
<MultiselectElement :close-on-select="false" />
Whether the option list should be closed after selecting an option.
closeOnDeselect
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :close-on-deselect="true" />
<MultiselectElement :close-on-deselect="false" />
Whether the option list should be closed after deselecting an option.
clearOnRefetch
- Type:
boolean
- Default:
true
Whether the value should be cleared when the options list is refetched while using String (endpoint) with variables.
delay
- Type:
number
- Default:
-1
- Native support:
false
<!-- No reload, internal filtering --->
<MultiselectElement :search="true" :delay="-1"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data
}" ...
/>
<!-- Instant reload, no internal filtering -->
<MultiselectElement :search="true" :delay="0" :filter-results="false"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data.filter((i) => {
return !searchQuery || i.indexOf(searchQuery) !== -1
})
}" ...
/>
<!-- Reload in 1000ms, no internal filtering -->
<MultiselectElement :search="true" :delay="1000" :filter-results="false"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data.filter((i) => {
return !searchQuery || i.indexOf(searchQuery) !== -1
})
}" ...
/>
The amount of milliseconds
to wait between the last change of the search query and the reload of async items
.
If it is 0
the items will be reloaded without delay when the search changes.
If it is -1
the items won't be reloaded upon search change, they will only be filtered internally.
If you have a remote set of data that you just want to load initially without filtering, you should set this to -1
to avoid unnecessary requests when the search query changes.
If you have a large set of data that actually needs filtering, make sure to set filterResults
to false
and take care of filtering manually by passing the searchQuery
param to the request.
To avoid loading large set of data initially or having too many results for a search query (like an 'a'
) you can set resolveOnLoad
to false
and define minChars
option.
If you want the option list to be emptied while fetching new items when the search query changes, set clearOnSearch
to true
.
minChars
- Type:
number
- Default:
0
- Native support:
false
<!-- Only refresh options when at least 2 characters are typed -->
<MultiselectElement :search="true" :delay="0" :filter-results="false" :resolve-on-load="false"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data.filter((i) => {
return !searchQuery || i.indexOf(searchQuery) !== -1
})
}"
:min-chars="2" ...
/>
The minimum number of characters required to refresh async items
. Thedelay
must be >= 0
in order to reload items when the search changes.
If it is 0
the items will be refreshed even when the search becomes empty.
You should set filterResults
to false
when you are filtering items manually in the async function to avoid unneccessary requests when the search changes.
You should set resolveOnLoad
to false
to avoid loading a large set of unfiltered initial data.
resolveOnLoad
- Type:
boolean
- Default:
true
- Native support:
false
<!-- All options are loaded initially -->
<MultiselectElement :search="true"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data.filter((i) => {
return !searchQuery || i.indexOf(searchQuery) !== -1
})
}"
:resolve-on-load="true" ...
/>
<!-- Options are only loaded on search -->
<MultiselectElement :search="true" :filter-results="false" :delay="0"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data.filter((i) => {
return !searchQuery || i.indexOf(searchQuery) !== -1
})
}"
:resolve-on-load="false" ...
/>
Whether to load async items
when the component is mounted.
Set this to false
if you have a large set of data that you only want to display after filtering, eg. in conjunction with minChars
option.
You need to set delay
to >= 0
in order to reload async items when the search changes.
You should set filterResults
to false
when you are filtering items manually in the async function to avoid unneccessary requests when the search changes.
filterResults
- Type:
boolean
- Default:
true
- Native support:
false
<!-- Internal filtering is enabled -->
<MultiselectElement :search="true" :filter-results="true" />
<!-- Internal filtering is disabled -->
<MultiselectElement :search="true" :filter-results="false" />
Whether options should be filtered internally based on the search query.
Set this to false
if you want to filter options manually, eg. in an async
function.
You need to set delay
to >= 0
in order to reload async items and perform manual filtering when the search changes.
You should set filterResults
to false
when you are filtering items manually in the async function to avoid unneccessary requests when the search changes.
clearOnSearch
- Type:
boolean
- Default:
false
- Native support:
false
<!-- Clears option list when reloading items --->
<MultiselectElement :search="true" :delay="1000" :filter-results="false"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data.filter((i) => {
return !searchQuery || i.indexOf(searchQuery) !== -1
})
}"
:clear-on-search="false" ...
/>
<!-- Doesn't clear option list when reloading items --->
<MultiselectElement :search="true" :delay="1000" :filter-results="false"
:items="async function(searchQuery) {
return (await axios.get('https://vueform.com/json/async-items')).data.filter((i) => {
return !searchQuery || i.indexOf(searchQuery) !== -1
})
}"
:clear-on-search="true" ...
/>
Whether options should be removed when async items
are being reloaded upon search query change.
hideSelected
- Type:
boolean
- Default:
true
- Native support:
false
<MultiselectElement :hide-selected="true" ... />
<MultiselectElement :hide-selected="false" ... />
Whether selected options should be hidden from the option list.
caret
- Type:
boolean
- Default:
true
- Native support:
false
<MultiselectElement :caret="true" ... />
<MultiselectElement :caret="false" ... />
Whether the multiselect should display a small triangle on the right.
loading
- Type:
boolean
- Default:
false
- Native support:
false
<MultiselectElement :loading="true" ... />
Manually triggers the loading state and displays a spinner on the right.
noOptionsText
- Type:
string|object
- Default:
locale.multiselect.noOptions
- Native support:
false
- Localizable:
true
<MultiselectElement no-options-text="No options" ... />
Overrides the default text that displays when the multiselect has no options.
noResultsText
- Type:
string|object
- Default:
locale.multiselect.noResults
- Native support:
false
- Localizable:
true
<MultiselectElement no-results-text="No results" :search="true" ... />
Overrides the default text that displays when the multiselect has no search results.
autocomplete
- Type:
string
- Default:
undefined
- Native support:
false
<MultiselectElement :search="true" autocomplete="off" ... />
Sets the autocomplete
attribute of the search input field when search: true
.
Hint: the value
'off'
might not disable autocomplete - read more about it here. Alternatively you can also setinputType
to'search'
.
inputType
- Type:
string
- Default:
text
- Native support:
false
<MultiselectElement :search="true" input-type="search" ... />
Sets the type
attribute of the search input field when search: true
.
extendOptions
- Type:
object
- Default:
{}
<MultiselectElement :extend-options="{ ... }" ... />
Additional props for @vueform/multiselect component. It can be used if the Multiselect component has any properties that Vueform has not implemented yet.
name
- Type:
string|number
- Default:
undefined
- Required:
true
<MultiselectElement name="element" ... />
Sets the element's name and the name
attribute of the multiselect.
id
- Type:
string
- Default:
null
<MultiselectElement id="field-id" ... />
Sets the id
attribute of the multiselect.
disabled
- Type:
boolean|function|array|object
- Default:
false
<MultiselectElement :disabled="true" :default="['Vue.js']" ... />
<MultiselectElement :disabled="prop" ... /> <!-- computed / data (ref) prop -->
<MultiselectElement :disabled="[['text', 'value']]" ... /> <!-- conditional -->
<MultiselectElement :disabled="(el$, form$) => { return /* boolean */ }" ... />
Disables the multiselect.
If can be a boolean
value.
It can be a computed / data (ref) prop.
It can be an array
of conditions. When all conditions are met the element will become disabled.
It can be a function that receives the el$
element instance and form$
form instance params and expected to return a boolean
.
attrs
- Type:
object
- Default:
{}
<MultiselectElement :attrs="{ autofocus: true }" ... />
Assigns HTML attributes to the container / input field.
label
- Type:
string|object|function
- Default:
null
- Localizable:
true
Sets a label for the element. Can be defined as a string
, a Vue component
object with a render function or as a function
that receives el$
as its first a param.
Can also be defined via
#label
slot.
placeholder
- Type:
string|object
- Default:
null
- Native support:
false
- Localizable:
true
<MultiselectElement placeholder="Placeholder" ... />
Sets the placeholder
attribute of the multiselect.
The value of placeholder
is automatically set as floating
if that's not defined. This behavior can be disabled on form level with floatPlaceholders: false
or globally in vueform.config.js
.
floating
- Type:
string|boolean|object
- Default:
null
- Localizable:
true
<MultiselectElement floating="Framework" :default="['Vue.js']" ... />
Renders a floating label above the element if that has value.
If floatPlaceholders
is enabled it can be disabled for this element by using :floating="false"
.
info
- Type:
string|object
- Default:
null
- Localizable:
true
<MultiselectElement label="Info" info="Info" ... />
Renders an ElementInfo
component next to the element's label. By default the icon shows the value of info
when hovered, which can contain plain text or HTML. The element needs to have a label
defined in order for info to be rendered.
Can be also defined via
#info
slot.
infoPosition
- Type:
string
- Default:
right
<MultiselectElement label="Top" info="Top" info-position="top" ... />
<MultiselectElement label="Right" info="Right" info-position="right" ... />
<MultiselectElement label="Left" info="Left" info-position="left" ... />
<MultiselectElement label="Bottom" info="Bottom" info-position="bottom" ... />
Sets the position of the info
tooltip.
Can be also defined via
#info
slot.
description
- Type:
string|object
- Default:
null
- Localizable:
true
<MultiselectElement description="Lorem ipsum dolor sit amet" ... />
Renders the contents of description
prop in the ElementDescription
component below the multiselect. It can contain plain text or HTML.
Can be also defined via
#description
slot.
before
- Type:
object|string|number
- Default:
null
- Localizable:
true
<MultiselectElement before="Before" ... />
Renders the contents of before
in a ElementText
component before the multiselect. It can contain plain text or HTML.
Can be also defined via
#before
slot.
between
- Type:
object|string|number
- Default:
null
- Localizable:
true
<MultiselectElement description="Description" between="Between" ... />
Renders the contents of between
in a ElementText
component between the multiselect and the description. It can contain plain text or HTML.
Can be also defined via
#between
slot.
after
- Type:
object|string|number
- Default:
null
- Localizable:
true
<MultiselectElement description="Description" rules="required" after="After" ... />
Renders the contents of after
in a ElementText
component after the description and error. It can contain plain text or HTML.
Can be also defined via
#after
slot.
default
- Type:
array
- Default:
[]
<MultiselectElement :default="['Vue.js']" ... />
Sets the default value for the multiselect.
formatData
- Type:
function
- Default:
null
<MultiselectElement :format-data="(n, v) => ({[n]: /* transformed value */ })" ... />
Formats the element's requestData
.
The first param is the element's name
, the second is the value
. The return value should be an object
, which only contains one item with the element's name
as key and the transformed value
as value.
formatLoad
- Type:
function
- Default:
null
<MultiselectElement :format-load="(v) => /* transformed value */" ... />
Formats the data being loaded to the element when using load(data, format: true)
. It receives the value being loaded to the element as its first param and should return the formatted value of the element.
submit
- Type:
boolean
- Default:
true
<MultiselectElement :submit="false" ... />
If set to false
the element's data will not be included in requestData
and will not be submitted.
rules
- Type:
array|string|object
- Default:
null
<MultiselectElement rules="required|min:2" ... />
<MultiselectElement :rules="['required', 'min:2']" ... />
The validation rules to be applied for the element.
The list of rules can be defined as a string
separated by |
or as an array
, where each item should be a single validation rule.
fieldName
- Type:
string
- Default:
name|label
<MultiselectElement field-name="Field name" rules="required" ... />
Sets the name of the field in validation rule messages.
messages
- Type:
object
- Default:
{}
<MultiselectElement rules="required" :messages="{ required: 'Please select at least one item' }" ... />
Overrides the default messages for the element's validation rules. The value is an object
where each key is the name of a validation rule and the value is the error message that will be displayed when the rule fails.
You can override validation messages on form level with
messages
.
conditions
- Type:
array
- Default:
[]
<!-- field1 - type 'show' -->
<TextElement name="field1" ... />
<!-- field2 - only if field1 == 'show' -->
<MultiselectElement name="field2" :conditions="[['field1', 'show']]" ... />
<!-- field3 - only if field1 != 'show' -->
<MultiselectElement name="field3" :conditions="[['field1', '!=', 'show']]" ... />
<!-- field4 - only if field1 == 'show' -->
<MultiselectElement name="field4" :conditions="[
(form$, el$) => form$.el$('field1')?.value === 'show'
]" ... />
Shows or hides an element based on the provided conditions.
If an element's conditions are unmet the element will be hidden and its available
property will become false
. If hidden, its value will not be part of requestData
.
Conditions can be provided as an array
, where each item has to be either an array
or a function
. The element will only become available
if all the conditions are fulfilled.
If a condition is provided as an array
, the first value must be the path
of an other field which value should be watched. The second is an operator that defines the type of comparison. The third is the expected value of the other field.
<MultiselectElement name="field" :conditions="[['other_field', '==', 'expected_value']]" ... />
Hint: In case you want to check for equality you might leave the operator and pass the expected value as the second param:
<MultiselectElement name="field" :conditions="[['other_field', 'expected_value']]" ... />
Available operators:
==
- expect equality!=
- expect inequality>
- expect the other element's value(s) to be higher>=
- expect the other element's value(s) to be higher or equal<
- expect the other element's value(s) to be lower<=
- expect the other element's value(s) to be lower or equal^
- expect the other element's value to start with$
- expect the other element's value to end with*
- expect the other element's value to containin
- expect to be among an array of valuesnot_in
- expect not to be among an array of valuestoday
- expect to be todaybefore
- expect to be before a date (value can be aYYYY-MM-DD
date string ortoday
)after
- expect to be after a date (value can be aYYYY-MM-DD
date string ortoday
)
The expected value can also be defined as an array
in which case any of its values will fulfill the condition.
Conditions can be defined with OR
relation or as function
. Learn more about conditions here.
columns
- Type:
object|string|number
- Default:
null
<MultiselectElement label="Label" :columns="{ container: 12, label: 3, wrapper: 12 }" ... />
Sets the size of the container
, label
and wrapper
using the theme's grid system, where the:
container
is the outermost DOM that contains bothlabel
andwrapper
label
contains the labelwrapper
contains the multiselect.
container: 12
label: 3
wrapper: 12
The value of container
defines the size of the element's container. 12
will result in full width, 6
in half, 4
in third and so on.
The value of label
defines the amount of space the label should take up within the container. If the container
is 12
and label
is 6
the label is going to take up half the space and the multiselect will the other half (which is calculated automatically). If the container
is 6
and label
is 6
, the label will only take up one forth and the multiselect the rest. In case the label
has full width (12
) the multiselect will also take up full space instead of becoming zero.
The value of wrapper
defines the size of the multiselect wrapper within the space left for it in the container after subtracting the size of the label. If the container
is 12
and label
is 4
the space left for the multiselect is 8
. In this case if the wrapper
value is 12
it will take up the full space left for it (which is 8
) while if it is changed to 6
it will only take up half the space left for it (4
):
<MultiselectElement label="Label" :columns="{ container: 12, label: 4, wrapper: 12 }" ... />
<MultiselectElement label="Label" :columns="{ container: 12, label: 4, wrapper: 6 }" ... />
Note that while the size of the multiselect wrapper changes, the size of extras like a description or error won't be limited to the wrapper's space. Instead it will take up the full space in the container left after subtracting the size of the label:
<MultiselectElement
label="Label"
:columns="{ container: 12, label: 4, wrapper: 6 }"
description="Lorem ipsum dolor sit amet, consectetur adipiscing elit"
... />
You can set the value of columns
as a number
in which case the container
will receive its value without affecting the default settings of label
and wrapper
:
<MultiselectElement label="Label" :columns="6" ... /> <!-- { container: 6, label: 3, wrapper: 12 } -->
You can as well define column values for different breakpoints using the theme system's breakpoints like sm
, md
, etc. as keys:
<MultiselectElement label="Label" :columns="{
xs: { container: 12, label: 12, wrapper: 12 },
sm: { container: 12, label: 4, wrapper: 12 },
md: 12,
lg: { container: 12, label: 2, wrapper: 12 }
}" ... />
Default column sizes can be defined globally in
vueform.config.js
or on form level usingcolumns
.
inline
- Type:
boolean
- Default:
false
<MultiselectElement :inline="true" ... />
Renders the element and all of its components in a single <span>
without applying columns
.
size
- Type:
string
- Default:
undefined
<MultiselectElement size="sm" ... />
<MultiselectElement ... /> <!-- Default size: 'md' -->
<MultiselectElement size="lg" ... />
The size of the element and its child components.
view
- Type:
string
- Default:
undefined
<MultiselectElement view="alt" ... />
The name of the view to be used for the element and by default for its child components. If undefined
the default view will be used. Child component views can be overridden with views
option.
Learn more about views here.
views
- Type:
object
- Default:
{}
<MultiselectElement :views="{
ComponentName: 'alt'
}" ... />
The name of the views for the child components.
Learn more about views here.
addClasses
- Type:
object|function
- Default:
{}
<MultiselectElement :add-classes="{
ComponentName: {
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}
}" ... />
Adds classes to any component's class names. The classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :add-classes="(form$) => ({
ComponentName: {
classname: [
{ 'class-value': form$.el$('other_field')?.value === 'some_value' }
],
}
})" ... />
Learn more about adding classes here.
addClass
- Type:
array|object|string|function
- Default:
null
<MultiselectElement :add-class="{
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}" ... />
Adds classes to any of MultiselectElement
component's class names. Classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :add-class="(form$) => ({
classname: [
{ 'class-value': form$.el$('other_field')?.value === 'some_value' }
],
})" ... />
Learn more about adding classes here.
removeClasses
- Type:
object|function
- Default:
{}
<MultiselectElement :remove-classes="{
ComponentName: {
classname: ['class-value-1', 'class-value-2']
}
}" ... />
Removes classes from any class names of any components. The classes to be removed must be listed in an array
.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :remove-classes="(form$) => ({
ComponentName: {
classname: form$.el$('other_field')?.value === 'some_value'
? ['class-value-1', 'class-value-2']
: [],
}
})" ... />
Learn more about removing classes here.
removeClass
- Type:
array|object|function
- Default:
null
<MultiselectElement :remove-class="{
classname: ['class-value-1', 'class-value-2']
}" ... />
Removes classes from any of MultiselectElement
component's class names. The classes to be removed must be listed in an array
.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :remove-class="(form$) => ({
classname: form$.el$('other_field')?.value === 'some_value'
? ['class-value-1', 'class-value-2']
: [],
})" ... />
Learn more about removing classes here.
replaceClasses
- Type:
object|function
- Default:
{}
<MultiselectElement :replace-classes="{
ComponentName: {
classname: {
'from-class': 'to-class',
'from-class': ['to-class'],
'from-class': [{'to-class': true}],
}
}
}" ... />
Replaces classes of any class names of any component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string
or an array
. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :replace-classes="(form$) => ({
ComponentName: {
classname: form$.el$('other_field')?.value === 'some_value' ? {
'from-class': 'to-class'
} : {},
}
})" ... />
Learn more about replacing classes here.
replaceClass
- Type:
object|function
- Default:
null
<MultiselectElement :replace-class="{
classname: {
'from-class': 'to-class',
'from-class': ['to-class'],
'from-class': [{'to-class': true}],
}
}" ... />
Replaces the classes of any class names of MultiselectElement
component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string
or an array
. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :replace-class="(form$) => ({
classname: form$.el$('other_field')?.value === 'some_value' ? {
'from-class': 'to-class'
} : {},
})" ... />
Learn more about replacing classes here.
overrideClasses
- Type:
object|function
- Default:
{}
<MultiselectElement :override-classes="{
ComponentName: {
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}
}" ... />
Overrides the classes of any component's class names. The classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :override-classes="(form$) => ({
ComponentName: form$.el$('other_field')?.value === 'some_value' ? {
classname: 'class-value'
} : {}
})" ... />
Learn more about overriding classes here.
overrideClass
- Type:
array|object|string|function
- Default:
null
<MultiselectElement :override-classes="{
ComponentName: {
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}
}" ... />
Overrides the classes of any of MultiselectElement
component's class names. The classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MultiselectElement :override-class="(form$) => (form$.el$('other_field')?.value === 'some_value' ? {
classname: 'class-value'
} : {})" ... />
Learn more about overriding classes here.
templates
- Type:
object
- Default:
{}
<template>
<div id="app">
<Vueform>
<MultiselectElement :templates="{ ElementError }" ... />
</Vueform>
</div>
</template>
<script>
import { markRaw } from 'vue'
import CustomElementError from './CustomElementError.vue'
export default {
data() {
return {
ElementError: markRaw(CustomElementError),
}
}
}
</script>
Overrides templates used by the component.
Learn more about overriding templates here.
presets
- Type:
array
- Default:
[]
<MultiselectElement :presets="['preset1', 'preset2']" ... />
The presets to be applied for the component.
Learn more about presets classes here.
slots
- Type:
object
- Default:
{}
<script>
import { Vueform, useVueform } from '@vueform/vueform';
import CustomDescriptionSlot from 'path/to/CustomDescriptionSlot.vue';
export default {
mixins: [Vueform],
setup: useVueform,
data: () => ({
vueform: {
schema: {
element: {
type: 'multiselect',
slots: {
label: '<span>Label</span>',
description: CustomDescriptionSlot,
}
}
}
}
})
}
</script>
With this option you can define slot values in a schema based form that you would normally just write inline. The value of a slot can be a plain string, HTML or a component with render function.
While this option can be also used in inline forms, it's primarily intended for schema based forms.
Properties
Properties include data
, computed
and inject
properties of the component. You can use them by reaching the element's Vue component instance via form$
's el$(path)
method or directly via this
in options API or el$
in Composition API.
aria
- Type:
object
- Group:
computed
The aria-*
attributes of the input.
resolvedOptions
- Type:
array
- Group:
computed
Contains the resolved options.
Placeholder
- Type:
string
- Group:
computed
The localized placeholder of the element.
isRequired
- Type:
boolean
- Group:
computed
Whether the element is required (has required rule).
isDefault
- Type:
boolean
- Group:
computed
Whether the element has its default value.
value
- Type:
any
- Group:
computed
The value of the element.
model
- Type:
any
- Group:
computed
Intermediary value between element's value and field's v-model
. It is required when we need to transform the value format between the element and its field.
data
- Type:
object
- Group:
computed
The value of the element in {[name]: value}
value format. This gets merged with the parent component's data.
requestData
- Type:
object
- Group:
computed
Same as data
property except that it only includes the element's value if submit
is not disabled and available
is true
(has no conditions
or they are fulfilled).
empty
- Type:
boolean
- Group:
computed
Whether the element has no value filled in.
path
- Type:
string
- Group:
computed
The path of the element using dot .
syntax.
dataPath
- Type:
string
- Group:
computed
The path of the element's data using dot .
syntax.
parent
- Type:
VNode
- Group:
computed
The parent component of the element.
validated
- Type:
boolean
- Group:
computed
Whether the element was already validated at least once.
invalid
- Type:
boolean
- Group:
computed
Whether the element has any failing rules.
dirty
- Type:
boolean
- Group:
computed
Whether the element's value was modified.
pending
- Type:
boolean
- Group:
computed
Whether the element has any async rules in progress.
busy
- Type:
boolean
- Group:
computed
Whether the element is pending
.
messageBag
- Type:
MessageBag
- Default:
MessageBag
- Group:
data
Instance of MessageBag service. Custom errors and messages can be added.
errors
- Type:
array
- Group:
computed
All the errors of MessageBag
.
error
- Type:
string
- Group:
computed
The first error of MessageBag
.
available
- Type:
boolean
- Group:
computed
Whether no conditions
are defined or they are all fulfilled.
hidden
- Type:
boolean
- Default:
false
- Group:
data
visible
- Type:
boolean
- Group:
computed
Whether the element is visible. It's false
when available
or active
is false
or hidden
is true
.
focused
- Type:
boolean
- Group:
data
Whether the element is focused.
isDisabled
- Type:
boolean
- Group:
computed
Whether the element is disabled.
isLoading
- Type:
boolean
- Group:
computed
Whether the element is in loading state.
isSuccess
- Type:
boolean
- Group:
computed
Whether the element has been filled in successfully.
isDanger
- Type:
boolean
- Group:
computed
Whether the element has errors.
container
- Type:
HTMLElement
- Group:
data
The ref to the outermost DOM of the element.
input
- Type:
HTMLElement
- Group:
data
The main input field of the element, which can be a Multiselect
component.
fieldId
- Type:
string
- Group:
computed
hasLabel
- Type:
boolean
- Group:
computed
Whether the element has a label
option, a #label slot or Vueform
component's forceLabels
option is true
.
hasFloating
- Type:
boolean
- Group:
computed
Whether the element floating label.
Size
- Type:
string
- Group:
computed
The resolved size of the element and all of its child components.
View
- Type:
string
- Group:
computed
The name of the resolved view for the component and the default view for its child components. Child component views can be overridden with views
option. This one should be used to determine the component's view in class functions.
template
- Type:
object
- Group:
computed
The component's template.
classes
- Type:
object
- Group:
computed
The component's classes.
theme
- Type:
object
- Group:
inject
The global theme object, which contains all the default templates and classes.
form$
- Type:
Vueform
- Group:
inject
The root form's component.
el$
- Type:
VueformElement
- Group:
computed
The element's component.
mounted
- Type:
boolean
- Default:
true
- Group:
data
Whether the element has been already mounted.
Methods
The methods
of the component that you can use by reaching the element's Vue component instance via form$
's el$(path)
method or directly via this
in options API or el$
in Composition API.
updateItems
- Arguments:
{boolean} disable*
- whether the input field should be disabled while fetching options
- Returns:
Promise
Fetches & updates select options when using async
options. Receives el$
as first param.
select
- Arguments:
{string|array} options*
- value(s) of the option(s) to select
- Returns:
void
Selects one or more options.
deselect
- Arguments:
{string|array} options*
- value(s) of the option(s) to deselect
- Returns:
void
Deselects one or more options.
clearMessages
- Returns:
void
Clears the manually added messages from the messageBag
.
load
- Arguments:
{any} value*
- the value to be loaded{boolean} format*
- whether the loaded value should be formatted withformatLoad
before setting the value of the element (default:false
)
- Returns:
void
Loads value to the element using optional formatLoad
formatter. This is the method that gets called for each element when loading data to the form with format: true
.
update
- Arguments:
{any} value*
- the value to be set
- Returns:
void
Updates the value of the element similarly to load
, only that it can't format data.
clear
- Returns:
void
Clears the element's value.
reset
- Returns:
void
Resets the element's value to default
(or empty if default
is not provided). Also resets all the validation state for the element.
disable
- Returns:
void
Disables the element.
enable
- Returns:
void
Enables the element even if it is disabled by disabled
option.
on
- Arguments:
{string} event*
- name of the event to listen for{function} callback*
- callback to run when the event is triggered
- Returns:
void
Adds a listener for an event.
off
- Arguments:
{string} event*
- name of the event to remove
- Returns:
void
Removes all listeners for an event.
fire
- Arguments:
{any} args*
- list of arguments to pass over to the event callback
- Returns:
void
Fires and emits an event.
validate
- Returns:
Promise
Checks each validation rule for the element (async).
clean
- Returns:
void
Removes the element's dirty
state.
resetValidators
- Returns:
void
Sets the validators to default state.
reinitValidation
- Returns:
void
Re-initializes validators when rules have changed.
hide
- Returns:
void
Hides the element.
show
- Returns:
void
Shows the element if it was hidden with hide()
method.
Events
With events you can subscribe to different events broadcasted by the element. It can be used inline as regular Vue event listeners with @event
format. In schema
it can be used in PascalCase format prefixed with on
(eg. onChange
).
<template>
<Vueform>
<MultiselectElement @{eventName}="handler" ... />
</Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'
export default {
mixins: [Vueform],
setup: useVueform,
data: () => ({
vueform: {
schema: {
element: {
type: 'multiselect',
on{EventName}() {
// ...
}
}
}
}
})
}
</script>
You can also use on(event, callback)
method to subscribe to events.
change
- Params:
{string} newValue
- the new value{string} oldValue
- the old value{component} el$
- the element's component
Triggered when the element's value is changed.
select
- Params:
{object} option
- the selected option{component} el$
- the element's component
Triggered when an option is selected when using native: false
.
deselect
- Params:
{object} option
- the deselected option{component} el$
- the element's component
Triggered when an option is deselected when using native: false
.
search-change
- Params:
{string|null} searchQuery
- the search value{component} el$
- the element's component
Triggered when the search query changes when using search: true
.
open
- Params:
{component} el$
- the element's component
Triggered when the dropdown list is opened when using native: false
.
close
- Params:
{component} el$
- the element's component
Triggered when the dropdown list is closed when using native: false
.
clear
- Params:
{component} el$
- the element's component
Triggered when the value is cleared when using native: true
.
paste
- Params:
{Event} event
- the paste Event{component} el$
- the element's component
Triggered when text is pasted to the search input when using search: true
.
beforeCreate
- Params:
{component} el$
- the element's component
Triggered in beforeCreate hook.
created
- Params:
{component} el$
- the element's component
Triggered in created hook.
beforeMount
- Params:
{component} el$
- the element's component
Triggered in beforeMount hook.
mounted
- Params:
{component} el$
- the element's component
Triggered in mounted hook.
beforeUpdate
- Params:
{component} el$
- the element's component
Triggered in beforeUpdate hook.
updated
- Params:
{component} el$
- the element's component
Triggered in updated hook.
beforeUnmount
- Params:
{component} el$
- the element's component
Triggered in beforeUnmount (or beforeDestroy in Vue 2) hook.
unmounted
- Params:
{component} el$
- the element's component
Triggered in unmounted (or destroyed in Vue 2) hook.
Slots
Slots can be used inline or in slots
option object when used in schema
:
<template>
<Vueform>
<MultiselectElement ... >
<template #{slot-name}="scope">
<!-- ... --->
</template>
</MultiselectElement>
</Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'
export default {
mixins: [Vueform],
setup: useVueform,
data: () => ({
vueform: {
schema: {
element: {
type: 'multiselect',
slots: {
{slotName}: // implementation
}
}
}
}
})
}
</script>
option
- Scope:
{component} el$
- the element's component{object} option
- the option object{string|null} search
- the current value of search input
Replaces the default option template.
<template>
<MultiselectElement
name="option_slot"
placeholder="Select employee"
track-by="name"
:close-on-select="false"
:search="true"
:items="[
{ value: 'judy', name: 'Judy', image: '/images/random-user-3.jpg' },
{ value: 'jane', name: 'Jane', image: '/images/random-user-4.jpg' },
{ value: 'john', name: 'John', image: '/images/random-user-1.jpg' },
{ value: 'joe', name: 'Joe', image: '/images/random-user-2.jpg' }
]"
>
<template v-slot:option="{ option }">
<img class="rounded-full w-6 h-6 mr-1.5" :src="option.image">
{{ option.name }}
</template>
</MultiselectElement>
</template>
<template>
<Vueform :schema :float-placeholders="false" />
</template>
<script setup>
import { ref } from 'vue'
const OptionWithImageSlot = {
props: ['option'],
render() {
return h('div', { class: 'flex' }, [
h('img', {
class: 'rounded-full w-6 h-6 mr-1.5',
src: this.option.image,
}),
this.option.name
])
}
}
const schema = ref({
multiselect: {
type: 'multiselect',
placeholder: 'Select employee',
trackBy: 'name',
closeOnSelect: false,
search: true,
items: [
{ value: 'judy', name: 'Judy', image: '/images/random-user-3.jpg' },
{ value: 'jane', name: 'Jane', image: '/images/random-user-4.jpg' },
{ value: 'john', name: 'John', image: '/images/random-user-1.jpg' },
{ value: 'joe', name: 'Joe', image: '/images/random-user-2.jpg' }
],
slots: {
option: OptionWithImageSlot,
}
}
})
</script>
multiple-label
- Scope:
{component} el$
- the element's component{array<object>} values
- the list of selected options
Replaces the input's inner label that is displayed when at least one option is selected.
placeholder
- Scope:
{component} el$
- the element's component
Replaces the default template for the input's placeholder
.
group-label
- Scope:
{component} el$
- the element's component{object} group
- the group object
Replaces the default group header when groups
is true
.
before-list
- Scope:
{component} el$
- the element's component
Prepends the content of the slot to the option list.
after-list
- Scope:
{component} el$
- the element's component
Appends the content of the slot to the option list.
no-results
- Scope:
{component} el$
- the element's component
Replaces the default template that is shown when the input has options, but the user search does not have any results. Can be also set without overriding the template with noResultsText
option.
no-options
- Scope:
{component} el$
- the element's component
Replaces the default template that is shown when the input has no options. Can be also set without overriding the template with noOptionsText
option.
caret
- Scope:
{component} el$
- the element's component
Replaces the small triangle displayed on the right of the input when caret
is true
.
spinner
- Scope:
{component} el$
- the element's component
Replaces the spinner shown when async options are loading or loading
is true
.
clear
- Scope:
{component} el$
- the element's component{function} clear
- clears the input value
Replaces the clear icon shown when the input has at least one selected options and canClear
is true
.
label
- Scope:
{component} el$
- the element's component
Renders a label for the element in ElementLabel
component.
info
- Scope:
{component} el$
- the element's component
Renders an info icon in ElementInfo
component next the the element label. When the icon is hovered it shows the content of this slot. The element needs to have a label to render this.
required
description
- Scope:
{component} el$
- the element's component
Renders description for the element in ElementDescription
component.
before
- Scope:
{component} el$
- the element's component
Renders an ElementText
component before the multiselect.
between
- Scope:
{component} el$
- the element's component
Renders an ElementText
component after the multiselect and before description.
after
- Scope:
{component} el$
- the element's component
Renders an ElementText
component after the description and error.