SelectElement

Renders a select input.

Basic Usage

<SelectElement> component can be used in a <Vueform> component:

<template>
  <Vueform>
    <SelectElement
      name="select"
      :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 SelectElement 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
<SelectElement :native="true" ... />
<SelectElement :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: {}

Defines the option list.

Can be a plain array where both the option value and label will be the same:

<SelectElement :items="['Vue.js', 'React', 'AngularJS']" ... />

Can be an plain object where the object key is the value and the value is the label of the option:

<SelectElement :items="{
  vuejs: 'Vue.js',
  react: 'React',
  angularjs: 'AngularJS'
}" ... />

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):

<SelectElement :items="[
  { value: 'vuejs', label: 'Vue.js' },
  { value: 'react', label: 'React' },
  { value: 'angularjs', label: 'AngularJS' },
]" ... />

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.

<SelectElement :items="async function(query){
  return await (axios.get('https://vueform.com/async-items.json')).data
}" ... />

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.

<SelectElement items="https://vueform.com/async-items.json" ... />

When options are defined as objects they can contain a disabled property that will disable the option:

<SelectElement :items="[
  { value: 'vuejs', label: 'Vue.js' },
  { value: 'react', label: 'React', disabled: true },
  { value: 'angularjs', label: 'AngularJS', disabled: true },
]" ... />

Hint: option template can be overridden with #option slot and selected option label with #single-label.

labelProp

  • Type: string
  • Default: label
<SelectElement 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
<SelectElement value-prop="id" ... />

The name of the object property that contains the option value when items is an array of objects.

  • Type: boolean
  • Default: false
  • Native support: false
<SelectElement :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
  • Default: label
  • Native support: false
<SelectElement track-by="name" ... />

The name of the object property that contains the text that should be searched when search is true and items is an array of objects.

strict

  • Type: boolean
  • Default: true
  • Native support: false
<SelectElement :strict="true" />
<SelectElement :strict="false" />

Whether the search should respect accents/diacritics.

create

  • Type: boolean
  • Default: false
  • Native support: false
<SelectElement :create="true" ... />

Whether the user can create new options. This will automatically enable search.

appendNewOption

  • Type: boolean
  • Default: true
  • Native support: false
<SelectElement :create="true" :append-new-option="true" ... />
<SelectElement :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
<SelectElement :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
  • ;
  • ,

object

  • Type: boolean
  • Default: false
  • Native support: false
<!-- With `object: false` -->
<SelectElement name="object_false" :native="false" :object="false" :items="[
  { label: 'Vue.js', value: 'vuejs' },
  { label: 'React', value: 'react' },
  { label: 'AngularJS', value: 'angularjs' },
]" ... />

<!-- With `object: true` -->
<SelectElement 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
<SelectElement :limit="2" :items="['Vue.js', 'React', 'AngularJS']" ... />

Limits the number of options to be displayed. The -1 value turns off the limit.

groups

  • Type: boolean
  • Default: false
  • Native support: false
<SelectElement :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 label
  • groupOptions defines the key for the group options
  • items are the list of options as you would regularly define without groups
  • disabled determines whether the group should be disabled (optional)

groupLabel

  • Type: string
  • Default: label
  • Native support: false
<SelectElement 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
<SelectElement 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
<SelectElement :group-hide-empty="true" ... />

Whether groups that have no items should be hidden.

openDirection

  • Type: string
  • Default: bottom
  • Native support: false
<SelectElement open-direction="top" />
<SelectElement open-direction="bottom" />

Whether the option list should appear on 'top' or 'bottom'. When displayed on 'top' the options are reversed.

canDeselect

  • Type: boolean
  • Default: true
  • Native support: false
<SelectElement :can-deselect="true" :can-clear="false" />
<SelectElement :can-deselect="false" :can-clear="false" />

Whether to allow deselecting a previously selected option.

If you don't want to allow empty values at all you also need to change canClear to false

canClear

  • Type: boolean
  • Default: true
  • Native support: false
<SelectElement :can-clear="true" />
<SelectElement :can-clear="false" />

Whether selected option can be cleared.

closeOnSelect

  • Type: boolean
  • Default: true
  • Native support: false
<SelectElement :close-on-select="true" />
<SelectElement :close-on-select="false" />

Whether the option list should be closed after selecting/deselecting an option.

delay

  • Type: number
  • Default: -1
  • Native support: false
<!-- No reload, internal filtering --->
<SelectElement :search="true" :delay="-1"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/async-items')).data
  }" ...
/>

<!-- Instant reload, no internal filtering -->
<SelectElement :search="true" :delay="0" :filter-results="false"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/async-items')).data.filter((i) => {
      return !searchQuery || i.indexOf(searchQuery) !== -1
    })
  }" ...
/>

<!-- Reload in 1000ms, no internal filtering -->
<SelectElement :search="true" :delay="1000" :filter-results="false"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/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 -->
<SelectElement :search="true" :delay="0" :filter-results="false" :resolve-on-load="false"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/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 -->
<SelectElement :search="true"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/async-items')).data.filter((i) => {
      return !searchQuery || i.indexOf(searchQuery) !== -1
    })
  }"
  :resolve-on-load="true" ...
/>

<!-- Options are only loaded on search -->
<SelectElement :search="true" :filter-results="false" :delay="0"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/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 -->
<SelectElement :search="true" :filter-results="true" />

<!-- Internal filtering is disabled -->
<SelectElement :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.

  • Type: boolean
  • Default: false
  • Native support: false
<!-- Clears option list when reloading items --->
<SelectElement :search="true" :delay="1000" :filter-results="false"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/async-items')).data.filter((i) => {
      return !searchQuery || i.indexOf(searchQuery) !== -1
    })
  }"
  :clear-on-search="false" ...
/>
<!-- Doesn't clear option list when reloading items --->
<SelectElement :search="true" :delay="1000" :filter-results="false"
  :items="async function(searchQuery) {
    return (await axios.get('https://vueform.com/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.

caret

  • Type: boolean
  • Default: true
  • Native support: false
<SelectElement :caret="true" ... />
<SelectElement :caret="false" ... />

Whether the select should display a small triangle on the right.

truncate

  • Type: boolean
  • Default: true
  • Native support: false
<SelectElement :truncate="false" :native="false" ... />
<SelectElement :truncate="true" :native="false" ... />

Whether the selected label should be truncated.

loading

  • Type: boolean
  • Default: false
  • Native support: false
<SelectElement :loading="true" ... />

Manually triggers the loading state and displays a spinner on the right.

noOptionsText

  • Type: string
  • Default: locale.multiselect.noOptions
  • Native support: false
<SelectElement no-options-text="No options" ... />

Overrides the default text that displays when the select has no options.

noResultsText

  • Type: string
  • Default: locale.multiselect.noResults
  • Native support: false
<SelectElement no-results-text="No results" :search="true" ... />

Overrides the default text that displays when the select has no search results.

autocomplete

  • Type: string
  • Default: undefined
  • Native support: false
<SelectElement :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 set inputType to 'search'.

inputType

  • Type: string
  • Default: text
  • Native support: false
<SelectElement :search="true" input-type="search" ... />

Sets the type attribute of the search input field when search: true.

extendOptions

  • Type: object
  • Default: {}
<SelectElement :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
<SelectElement name="element" ... />

Sets the element's name and the name attribute of the select.

id

  • Type: string
  • Default: null
<SelectElement id="field-id" ... />

Sets the id attribute of the select.

disabled

  • Type: boolean
  • Default: false
<SelectElement :disabled="true" ... />

Disables the select.

attrs

  • Type: object
  • Default: {}
<SelectElement :attrs="{ autofocus: true }" ... />

Assigns HTML attributes to the input field.

label

  • Type: string|object|function
  • Default: null

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
  • Default: null
<SelectElement placeholder="Placeholder" ... />

Sets the placeholder attribute of the select.

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
  • Default: null
<SelectElement floating="Select" ... />

Renders a floating label above the select if that has value.

If floatPlaceholders is enabled it can be disabled for this element by using :floating="false".

info

  • Type: string
  • Default: null
<SelectElement 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
<SelectElement label="Top" info="Top" info-position="top" ... />
<SelectElement label="Right" info="Right" info-position="right" ... />
<SelectElement label="Left" info="Left" info-position="left" ... />
<SelectElement label="Bottom" info="Bottom" info-position="bottom" ... />

Sets the position of the info tooltip.

Can be also defined via #info slot.

description

  • Type: string
  • Default: null
<SelectElement description="Lorem ipsum dolor sit amet" ... />

Renders the contents of description prop in the ElementDescription component below the select. It can contain plain text or HTML.

Can be also defined via #description slot.

before

  • Type: object|string|number
  • Default: null
<SelectElement before="Before" ... />

Renders the contents of before in a ElementText component before the select. It can contain plain text or HTML.

Can be also defined via #before slot.

between

  • Type: object|string|number
  • Default: null
<SelectElement description="Description" between="Between" ... />

Renders the contents of between in a ElementText component between the select and the description. It can contain plain text or HTML.

Can be also defined via #between slot.

after

  • Type: object|string|number
  • Default: null
<SelectElement 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: string|number|object
  • Default: null
<SelectElement default="Vue.js" ... />

Sets the default value for the select.

formatData

  • Type: function
  • Default: null
<SelectElement :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
<SelectElement :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
<SelectElement :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
<SelectElement rules="required|in:Vue.js,React" ... />
<SelectElement :rules="['required', 'in:Vue.js,React']" ... />

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
<SelectElement field-name="Field name" rules="required" ... />

Sets the name of the field in validation rule messages.

messages

  • Type: object
  • Default: {}
<SelectElement rules="required" :messages="{ required: 'Please select an option' }" ... />

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'
<SelectElement name="field2" :conditions="[['field1', 'show']]" ... />

// field3 - only if field1 != 'show'
<SelectElement name="field3" :conditions="[['field1', '!=', 'show']]" ... />

// field4 - only if field1 == 'show'
<SelectElement 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.

<SelectElement 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:

<SelectElement name="field" :conditions="[['other_field', 'expected_value']]" ... />

Available operators:

  • == - expects equality
  • != - expects inequality
  • not_in - expects not be be among an array of values
  • > - expects the other element's value to be higher
  • >=- expects the other element's value to be higher or equal
  • < - expects the other element's value to be lower
  • <= - expects the other element's value to be lower or equal

The expected value can also be defined as an array in which case any of its values will fulfill the condition.

A condition can also be defined as a function that returns a boolean. The function receives a form$ param (which the root form component). You can use the form$'s el$(path) method or data to reach any element's value within the form:

<SelectElement name="field" :conditions="[
  function(form$) {
    return form$.el$('other_field').value === 'expected_value'
  },
  function(form$) {
    return form$.data.other_field === 'expected_value'
  }
]" ... />

columns

  • Type: object|string|number
  • Default: null
<SelectElement 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 both label and wrapper
  • label contains the label
  • wrapper contains the select.
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 select 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 select the rest. In case the label has full width (12) the select will also take up full space instead of becoming zero.

The value of wrapper defines the size of the select 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 select 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):

<SelectElement label="Label" :columns="{ container: 12, label: 4, wrapper: 12 }" ... />
<SelectElement label="Label" :columns="{ container: 12, label: 4, wrapper: 6 }" ... />

Note that while the size of the select 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:

<SelectElement
  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:

<SelectElement 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:

<SelectElement 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 using columns.

inline

  • Type: boolean
  • Default: false
<SelectElement :inline="true" ... />

Renders the element and all of its components in a single <span> without applying columns.

size

  • Type: string
  • Default: undefined
<SelectElement size="sm" ... />
<SelectElement ... /> <!-- Default size: 'md' -->
<SelectElement size="lg" ... />

The size of the element and its child components.

view

  • Type: string
  • Default: undefined
<SelectElement 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: {}
<SelectElement :views="{
  ComponentName: 'alt'
}" ... />

The name of the views for the child components.

Learn more about views here.

addClasses

  • Type: object
  • Default: {}
<SelectElement :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.

Learn more about adding classes here.

addClass

  • Type: array|object|string
  • Default: null
<SelectElement :add-class="{
  classname: 'class-value',
  classname: ['class-value'],
  classname: [{'class-value': true}],
}" ... />

Adds classes to any of SelectElement 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.

Learn more about adding classes here.

removeClasses

  • Type: object
  • Default: {}
<SelectElement :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.

Learn more about removing classes here.

removeClass

  • Type: array|object
  • Default: null
<SelectElement :remove-class="{
  classname: ['class-value-1', 'class-value-2']
}" ... />

Removes classes from any of SelectElement component's class names. The classes to be removed must be listed in an array.

Learn more about removing classes here.

replaceClasses

  • Type: object
  • Default: {}
<SelectElement :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.

Learn more about replacing classes here.

replaceClass

  • Type: object
  • Default: null
<SelectElement :replace-class="{
  classname: {
    'from-class': 'to-class',
    'from-class': ['to-class'],
    'from-class': [{'to-class': true}],
  }
}" ... />

Replaces the classes of any class names of SelectElement 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.

Learn more about replacing classes here.

overrideClasses

  • Type: object
  • Default: {}
<SelectElement :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.

Learn more about overriding classes here.

overrideClass

  • Type: array|object|string
  • Default: null
<SelectElement :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any of SelectElement 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.

Learn more about overriding classes here.

templates

  • Type: object
  • Default: {}
<template>
  <div id="app">
    <Vueform>
      <SelectElement :templates="{ ElementError }" ... />
    </Vueform>
  </div>
</template>

<script>
import { markRaw } from 'vue' // '@vue/composition-api' in Vue.js 2
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: []
<SelectElement :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: 'select',
          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.

resolvedOptions

  • Type: array
  • Group: computed

Contains the resolved options.

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.

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

Whether the element was hidden programmatically with show() or hide() methods.

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.

input

  • Type: HTMLElement
  • Group: data

The main input field of the element.

fieldId

  • Type: string
  • Group: computed

The id of the select. If id is not provided path will be used.

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: component
  • Group: inject

The root form's component.

el$

  • Type: component
  • 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(disable)

  • Arguments:
    • {boolean} disable* - whether the input field should be disabled while fetching options
  • Returns: void

Fetches & updates select options when using async options. Receives el$ as first param.

.load(value, format)

  • Arguments:
    • {string} value* - the value to be loaded
    • {boolean} format* - whether the loaded value should be formatted with formatLoad 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(value)

  • Arguments:
    • {string|} 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(event, callback)

  • 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(event)

  • Arguments:
    • {string} event* - name of the event to remove
  • Returns: void

Removes all listeners for an event.

.fire(args)

  • Arguments:
    • {any} args* - list of arguments to pass over to the event callback
  • Returns: void

Fires and emits an event.

.validate()

  • Returns: void

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.

.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>
    <SelectElement @{eventName}="handler" ... />
  </Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'select',
          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>
    <SelectElement ... >
      <template #{slot-name}="scope">
        <!-- ... --->
      </template>
    </SelectElement>
  </Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'select',
          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.

<SelectElement
  name="option_slot"
  placeholder="Select employee"
  track-by="name"
  :close-on-select="false"
  :search="true"
  :items="[
    { value: 'judy', name: 'Judy', image: 'https://randomuser.me/api/portraits/med/women/1.jpg' },
    { value: 'jane', name: 'Jane', image: 'https://randomuser.me/api/portraits/med/women/2.jpg' },
    { value: 'john', name: 'John', image: 'https://randomuser.me/api/portraits/med/men/1.jpg' },
    { value: 'joe', name: 'Joe', image: 'https://randomuser.me/api/portraits/med/men/2.jpg' }
  ]"
>
    <template v-slot:option="{ option }">
      <img class="rounded-full w-6 h-6 mr-1.5" :src="option.image">
      {{ option.name }}
    </template>
</SelectElement>

#single-label

  • Scope:
    • {component} el$ - the element's component
    • {object} value - the selected option

Replaces the input's inner label that is displayed when an option is selected.

<SelectElement
  name="custom_single_label_slot"
  placeholder="Select employee"
  track-by="name"
  label-prop="name"
  default="john"
  :close-on-select="false"
  :search="true"
  :items="[
    { value: 'judy', name: 'Judy', image: 'https://randomuser.me/api/portraits/med/women/1.jpg' },
    { value: 'jane', name: 'Jane', image: 'https://randomuser.me/api/portraits/med/women/2.jpg' },
    { value: 'john', name: 'John', image: 'https://randomuser.me/api/portraits/med/men/1.jpg' },
    { value: 'joe', name: 'Joe', image: 'https://randomuser.me/api/portraits/med/men/2.jpg' }
  ]"
>
  <template v-slot:single-label="{ value }">
    <div class="flex items-center h-full absolute left-0 top-0 pointer-events-none bg-transparent leading-snug pl-3">
      <img class="rounded-full w-6 h-6 mr-1.5" :src="value.image"> {{ value.name }}
    </div>
  </template>
</SelectElement>

#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.

#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 select.

#between

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component after the select and before description.

#after

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component after the description and error.

 
Table of contents
Basic Usage Options Properties Methods Events Slots