@vueform/multiselect

Vue 3 multiselect by Vueform

About Vueform

Vueform is form library for Vue 2 & 3 with 30+ elements, file uploads, element nesting, 50+ validators, conditions, form steps and many more including reactive configuration, API access and ESM modules. Check out our live demos or see all the features and sign up for beta to get early access.

Multiselect features

• Vue 2 & 3 support
• No dependencies
• Lightweight (~5 kB gzipped)
• 100% coverage
• ESM support
• Single select options
• Multiple select options
• Tags
• Async options
• Search & filtering
• Custom slots
• Events
• Fully configurable

Installation

npm install @vueform/multiselect

Usage with Vue 3

<template>
  <div>
    <Multiselect
      v-model="value"
      :options="options"
    />
  </div>
</template>

<script>
  import Multiselect from '@vueform/multiselect'

  export default {
    components: {
      Multiselect,
    },
    data() {
      return {
        value: null,
        options: [
          'Batman',
          'Robin',
          'Joker',
        ]
      }
    }
  }
</script>

<style src="@vueform/multiselect/themes/default.css"></style>

Usage with Vue 2

When using with Vue 2 make sure to install @vue/composition-api first and change the imported module to:

import Multiselect from '@vueform/multiselect/dist/multiselect.vue2.js'

Demo

Demo

Basic props

Name	Type	Default	Description
mode	string	single	Possible values: single|multiple|tags.
options	array|object|function	[]	List of options. Can be: - an array (eg. [1,2,3]) - an object (eg. {a:1,b:2,c:3}) - an array of objects [{value:1,label:'v1'},{value:2,label:'v2'},{value:3,label:'v3'}] - a function returning a Promise (async function) with query input param. The promise should return options as an object or as an array of objects. When an array of objects is provided it must have a value property as well as properties that equal to :trackBy's and :label's value (both configurable with default value of 'label').
value (for Vue 2)	string|number|array	null	The variable that should store the select value when using Vue 2. If v-model is used it does not need to be set.
modelValue (for Vue 3)	string|number|array	null	The variable that should store the select value when using Vue 3. If v-model is used it does not need to be set.
searchable	boolean	false	Whether the options should be searchable.
trackBy	string	label	The name of the property that should be searched when searchable is true and an array of objects are provided as :options.
placeholder	string	null	The text that should be displayed before an options are selected.
label	string	'label'	If you provide an array of objects as options this property of those objects will be displayed for options and selected label.
multipleLabel	function		A function that should return how the label should be displayed when using multiple mode. It receives value as an argument. By default it renders 1 option selected and [n] options selected based on value length.
disabled	boolean	false	Whether the input should be disabled.
limit	number	-1	The maximum number of options that should be displayed. If -1 it won't be limited.
loading	boolean	false	Whether a loading spinner should be shown.
id	string	'multiselect'	The id of the multiselect container DOM.
caret	boolean	true	Whether should display a caret (small triangle on the right).
maxHeight	number	160	The maximum height of options list.
noOptionsText	string	'The list is empty'	The text that should be displayed when options list is empty.
noResultsText	string	No results found	The text that should be when there are no search results.

Advanced Props

Name	Type	Default	Description
clearOnSearch (async options)	boolean	false	Whether the option list should be cleared when a new character is typed before loading new options list using async options.
clearOnSelect (async options)	boolean	true	Whether the option list should be cleared upon selecting an option when using async options.
delay (async options)	number	-1	The delay in milliseconds that should occur between the last typed character and refreshing an async option list. If -1 the option list will not refresh when the search query changes. If 0 it will refresh without delay.
filterResults (async options)	boolean	true	Whether option list should be filtered by search query. This may be set to false if you are handling filtering when returning async options.
minChars (async options)	number	0	The minimum number of characters that should be typed to refresh async option list. If 0 it will refresh even when the search field becomes empty.
resolveOnLoad (async options)	boolean	true	Whether async options should be loaded initially (with an empty query). This should be true if you are planning to load non-object value(s) initially while using async options (to fetch matching objects for values).
appendNewTag (tags)	boolean	true	Whether should append new tag automatically to option list when using tags mode with createTag. If set to false you need to take care of appending a new tag to the provided :options list upon @tag event.
createTag (tags)	boolean	false	Whether should allow creating new tag based on search query when using tags mode.
hideSelected (multiple, tags)	boolean	true	Whether selected options should be excluded from the option list when using multiple or tags mode.
object	boolean	false	Whether the value should be stored as an object. If false: value: ['js','jsx','ts'] If true: value: [   {value:'js',label:'Javascript'},   {value:'jsx',label:'JSX'},   {value:'ts',label:'Typescript'} ]

Events

Event	Attributes	Description
@change	value	Emitted after the value is changed.
@close		Emitted after closing the option list.
@deselect	option	Emitted after an option is deselected or a tag is removed.
@open		Emitted after opening the option list.
@search-change	query	Emitted after a character is typed.
@select	option	Emitted after an option or tag is selected.
@tag	query	Emitted after enter is hit when a new tag is being created.

Slots

Slot	Attributes	Description
afterlist		Rendered after the options list.
beforelist		Rendered before the options list.
multiplelabel	values	Rendered when using multiple mode and options are selected. By default it renders the return value of multipleLabel function.
nooptions		Rendered when the options list is empty. By default renders noOptionsText.
noresults		Rendered when there are no search results. By default renders noResultsText.
option	option, search	Renders an option in options list.
singlelabel	value	Rendered when using single mode and an option is selected. By default it renders the :label if the selected option.
tag	option, remove, disabled	Renders a tag when using tags mode. When disabled the remove icon should not be displayed. The remove prop should be used to trigger the removal of the tag.

Note: the reason we don't use camelCase is because they are normalized back to lowercase when written in DOM.

Examples

• Single select
• Multiselect with object options
• Tags with search and array of objects options
• Tags with create
• Autocomplete with async options
• Tags with async options
• Select with custom options slot
• Multiselect with custom label slot
• Tags with custom tags slot

Single select

<Multiselect
  v-model="value"
  :options="['Batman', 'Robin', 'Joker']"
/>

JSFiddle - Example #1

Multiselect with object options

<Multiselect
  v-model="value"
  mode="multiple"
  :options="{
    batman: 'Batman',
    robin: 'Robin',
    joker: 'Joker'
  }"
/>

JSFiddle - Example #2

Tags with search and array of objects options

<Multiselect
  v-model="value"
  mode="tags"
  :searchable="true"
  :options="[
    { value: 'batman', label: 'Batman' },
    { value: 'robin', label: 'Robin' },
    { value: 'joker', label: 'Joker' },
  ]"
/>

JSFiddle - Example #3

Tags with create

<Multiselect
  v-model="value"
  mode="tags"
  :searchable="true"
  :createTag="true"
  :options="[
    { value: 'batman', label: 'Batman' },
    { value: 'robin', label: 'Robin' },
    { value: 'joker', label: 'Joker' },
  ]"
/>

JSFiddle - Example #4

Autocomplete with async options

<Multiselect
  v-model="value"
  placeholder="Choose a programming language"
  :filterResults="false"
  :minChars="1"
  :resolveOnLoad="false"
  :delay="0"
  :searchable="true"
  :options="async function(query) {
    return await fetchLanguages(query) // check JS block for implementation
  }"
/>

JSFiddle - Example #5

Tags with async options

<Multiselect
  v-model="value"
  mode="tags"
  placeholder="Choose your stack"
  :filterResults="false"
  :minChars="1"
  :resolveOnLoad="false"
  :delay="0"
  :searchable="true"
  :options="async function(query) {
    return await fetchLanguages(query) // check JS block for implementation
  }"
/>

JSFiddle - Example #6

Select with custom options slot

<Multiselect
  v-model="value"
  placeholder="Select your character"
  label="name"
  :options="[
    { value: 'captainamerica', name: 'Captain America', icon: 'https://cdn2.iconfinder.com/data/icons/avengers-filled/48/03_-_Captain_America_-_infinity_war_-_end_game_-_marvel_-_avengers_-_super_hero-512.png' },
    { value: 'spiderman', name: 'Spiderman', icon: 'https://cdn2.iconfinder.com/data/icons/avengers-filled/48/12_-_Spiderman_-_infinity_war_-_end_game_-_marvel_-_avengers_-_super_hero-512.png' },
    { value: 'ironman', name: 'Iron Man', icon: 'https://cdn2.iconfinder.com/data/icons/avengers-filled/48/02_-_IRONMAN_-_infinity_war_-_end_game_-_marvel_-_avengers_-_super_hero-512.png' },
  ]"
>
  <template v-slot:singlelabel="{ value }">
    <div class="multiselect-single-label">
      <img class="character-label-icon" :src="value.icon"> {{ value.name }}
    </div>
  </template>

  <template v-slot:option="{ option }">
    <img class="character-option-icon" :src="option.icon"> {{ option.name }}
  </template>
</Multiselect>

JSFiddle - Example #7

Multiselect with custom label slot

<Multiselect
  v-model="value"
  mode="multiple"
  placeholder="Select your characters"
  :options="{
    batman: 'Batman',
    robin: 'Robin',
    joker: 'Joker'
  }"
>
  <template v-slot:multiplelabel="{ values }">
    <div class="multiselect-multiple-label">
      {{ values.length }} characters selected
    </div>
  </template>
</Multiselect>

JSFiddle - Example #8

Tags with custom tags slot

<template>
  <Multiselect
    v-model="value"
    mode="tags"
    placeholder="Select employees"
    trackBy="name"
    label="name"
    :search="true"
    :options="[
      { 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:tag="{ option, remove, disabled }">
        <div class="multiselect-tag is-user">
          <img :src="option.image">
          {{ option.name }}
          <i
            v-if="!disabled"
            @click.prevent
            @mousedown.prevent="remove(option)"
          />
        </div>
      </template>
  </Multiselect>
</template>

<style>
  .multiselect-tag.is-user {
    padding: 5px 8px;
    border-radius: 22px;
    background: #35495e;
    margin: 3px 3px 8px;
  }

  .multiselect-tag.is-user img {
    width: 18px;
    border-radius: 50%;
    height: 18px;
    margin-right: 8px;
    border: 2px solid #ffffffbf;
  }

  .multiselect-tag.is-user i:before {
    color: #ffffff;
    border-radius: 50%;;
  }

  .user-image {
    margin: 0 6px 0 0;
    border-radius: 50%;
    height: 22px;
  }
</style>

JSFiddle - Example #9

License

MIT

Changelog

v1.1.3

2020-12-19

🐞 Bug Fixes

• Breaking: Renamed slots to lowercase instead of camel case because of DOM issue

🎉 Feature

• Added change event
• Breaking: renamed hideSelectedTag to hideSelected