vue-multiselect

What is vue-multiselect?

vue-multiselect is a powerful and flexible Vue.js component for creating dropdowns with multi-select capabilities. It supports single and multiple selections, tagging, filtering, and custom rendering of options.

What are vue-multiselect's main functionalities?

Single Select

This feature allows users to select a single option from a dropdown list. The `multiple` prop is set to `false` to enable single selection.

<template>
  <multiselect v-model="selected" :options="options" :multiple="false"></multiselect>
</template>

<script>
import Multiselect from 'vue-multiselect';

export default {
  components: { Multiselect },
  data() {
    return {
      selected: null,
      options: ['Option 1', 'Option 2', 'Option 3']
    };
  }
};
</script>

Multiple Select

This feature allows users to select multiple options from a dropdown list. The `multiple` prop is set to `true` to enable multiple selections.

<template>
  <multiselect v-model="selected" :options="options" :multiple="true"></multiselect>
</template>

<script>
import Multiselect from 'vue-multiselect';

export default {
  components: { Multiselect },
  data() {
    return {
      selected: [],
      options: ['Option 1', 'Option 2', 'Option 3']
    };
  }
};
</script>

Tagging

This feature allows users to add new options (tags) to the dropdown list. The `taggable` prop is set to `true`, and the `@tag` event is used to handle the addition of new tags.

<template>
  <multiselect v-model="selected" :options="options" :taggable="true" @tag="addTag"></multiselect>
</template>

<script>
import Multiselect from 'vue-multiselect';

export default {
  components: { Multiselect },
  data() {
    return {
      selected: [],
      options: ['Option 1', 'Option 2', 'Option 3']
    };
  },
  methods: {
    addTag(newTag) {
      this.options.push(newTag);
      this.selected.push(newTag);
    }
  }
};
</script>

Custom Option Rendering

This feature allows users to customize the rendering of options in the dropdown list. The `custom-label` prop is used to define a method that returns a custom label for each option.

<template>
  <multiselect v-model="selected" :options="options" :custom-label="customLabel"></multiselect>
</template>

<script>
import Multiselect from 'vue-multiselect';

export default {
  components: { Multiselect },
  data() {
    return {
      selected: null,
      options: [
        { name: 'Option 1', id: 1 },
        { name: 'Option 2', id: 2 },
        { name: 'Option 3', id: 3 }
      ]
    };
  },
  methods: {
    customLabel(option) {
      return `${option.name} (ID: ${option.id})`;
    }
  }
};
</script>

Other packages similar to vue-multiselect

vue-select

vue-select is a Vue.js component that provides a similar set of features to vue-multiselect, including single and multiple selections, tagging, and custom option rendering. It is known for its simplicity and ease of use.

vue-multiselect-next

vue-multiselect-next is a fork of vue-multiselect that aims to provide additional features and improvements. It offers similar functionalities with enhanced performance and additional customization options.

vue-treeselect

vue-treeselect is a multi-select component with nested options support. It is particularly useful for hierarchical data structures and provides features like single and multiple selections, search, and custom rendering.

README

vue-multiselect

Probably the most complete selecting solution for Vue.js, without jQuery.

Features & characteristics:

• NO dependencies
• Single select
• Multiple select
• Tagging
• Dropdowns
• Filtering
• Search with suggestions
• Logic split into mixins
• Basic component and support for custom components
• Vuex support
• Async options support
• > 95% test coverage
• Fully configurable (see props list below)

Demo & docs

http://monterail.github.io/vue-multiselect/

Install & basic usage

npm install vue-multiselect

<template>
  <div>
    <multiselect :selected.sync="selected" :options="options"></multiselect>
  </div>
</template>

It is very important not to mix .sync with :on-change prop. You have to either choose two-way binding or one way binding with :on-change callback as a way to update the :selected value

import Multiselect from 'vue-multiselect'
export default {
  components: { Multiselect },
  data () {
    return {
      selected: null,
      options: ['list', 'of', 'options']
    }
  }
}

You can now author custom components based on vue-multiselect mixins.

import { multiselectMixin, pointerMixin } from 'vue-multiselect'
export default {
  mixins: [multiselectMixin, pointerMixin],
  data () {
    return {
      selected: null,
      options: ['list', 'of', 'options']
    }
  }
}

Roadmap:

• 1.0 Release – Event based, deprecate two-way binding, make it easy to migrate to Vue 2.0
• Examples of custom components / templates ready to use in project
• Better documentation

Examples

in jade-lang/pug-lang

Single select / dropdown

multiselect(
  :options="source",
  :selected.sync="value",
  :multiple="false",
  :searchable="false",
  placeholder="Select one",
  label="name",
  :close-on-select="false",
  :allow-empty="false",
  key="name"
)

Single select with search

multiselect(
  :options="source",
  :selected.sync="value",
  :multiple="false",
  :searchable="true",
  placeholder="Select one",
  label="name",
  :close-on-select="true",
  :clear-on-select="false"
  key="name"
)

Multiple select with search

multiselect(
  :options="source",
  :selected.sync="multiValue",
  :multiple="true",
  :searchable="true",
  placeholder="Pick some",
  label="name",
  :close-on-select="true"
  key="name"
)

Tagging

with :on-tag and :on-change callback functions

multiselect(
  :options="taggingOptions",
  :selected="taggingSelected",
  :multiple="multiple",
  :searchable="searchable",
  :on-tag="addTag",
  :on-change="updateSelectedTagging",
  :taggable="true",
  tag-placeholder="Add this as new tag"
  placeholder="Type to search or add tag"
  label="name"
  key="code"
)

addTag (newTag) {
  const tag = {
    name: newTag,
    code: newTag.substring(0, 2) + Math.floor((Math.random() * 10000000))
  }
  this.taggingOptions.push(tag)
  this.taggingSelected.push(tag)
},

Vuex supporting example

with :on-change callback function

multiselect(
  :options="source",
  :selected="value",
  :multiple="false",
  :searchable="false",
  placeholder="Select one",
  :on-change="onChangeAction"
)

methods: {
  onChangeAction (newValue) {
    dispatch('SET_SELECT_VALUE', newValue)
  }
}

Asynchronous dropdown

multiselect(
  :options="countries",
  :selected.sync="selectedCountries",
  :multiple="multiple",
  :searchable="searchable",
  placeholder="Type to search",
  :on-search-change="asyncFind",
  label="name"
  key="code"
)
  span(slot="noResult").
    Oops! No elements found. Consider changing the search query.

methods: {
  asyncFind (query) {
    this.countries = findService(query)
  }
}

Props config

// multiselectMixin.js

props: {
  /**
   * Array of available options: Objects, Strings or Integers.
   * If array of objects, visible label will default to option.label.
   * If `labal` prop is passed, label will equal option['label']
   * @type {Array}
   */
  options: {
    type: Array,
    required: true
  },
  /**
   * Equivalent to the `multiple` attribute on a `<select>` input.
   * @default false
   * @type {Boolean}
   */
  multiple: {
    type: Boolean,
    default: false
  },
  /**
   * Required. Presets the selected options. Add `.sync` to
   * update parent value. If this.onChange callback is present,
   * this will not update. In that case, the parent is responsible
   * for updating this value.
   * @type {Object||Array||String||Integer}
   */
  selected: {
    required: true
  },
  /**
   * Key to compare objects
   * @default 'id'
   * @type {String}
   */
  key: {
    type: String,
    default: false
  },
  /**
   * Label to look for in option Object
   * @default 'label'
   * @type {String}
   */
  label: {
    type: String,
    default: false
  },
  /**
   * Enable/disable search in options
   * @default true
   * @type {Boolean}
   */
  searchable: {
    type: Boolean,
    default: true
  },
  /**
   * Clear the search input after select()
   * @default true
   * @type {Boolean}
   */
  clearOnSelect: {
    type: Boolean,
    default: true
  },
  /**
   * Hide already selected options
   * @default false
   * @type {Boolean}
   */
  hideSelected: {
    type: Boolean,
    default: false
  },
  /**
   * Equivalent to the `placeholder` attribute on a `<select>` input.
   * @default 'Select option'
   * @type {String}
   */
  placeholder: {
    type: String,
    default: 'Select option'
  },
  /**
   * Sets maxHeight style value of the dropdown
   * @default 300
   * @type {Integer}
   */
  maxHeight: {
    type: Number,
    default: 300
  },
  /**
   * Allow to remove all selected values
   * @default true
   * @type {Boolean}
   */
  allowEmpty: {
    type: Boolean,
    default: true
  },
  /**
   * Callback function to call after this.value changes
   * @callback onChange
   * @default false
   * @param {Array||Object||String||Integer} Current this.value
   * @param {Integer} $index of current selection
   * @type {Function}
   */
  onChange: {
    type: Function,
    default: false
  },
  /**
   * Callback function to call after this.search changes
   * @callback onSearchChange
   * @default false
   * @param {String} Pass current search String
   * @type {Function}
   */
  onSearchChange: {
    type: Function,
    default: false
  },
  /**
   * Value that indicates if the dropdown has been used.
   * Useful for validation.
   * @default false
   * @type {Boolean}
   */
  touched: {
    type: Boolean,
    default: false
  },
  /**
   * Reset this.value, this.search, this.selected after this.value changes.
   * Useful if want to create a stateless dropdown, that fires the this.onChange
   * callback function with different params.
   * @default false
   * @type {Boolean}
   */
  resetAfter: {
    type: Boolean,
    default: false
  },
  /**
   * Enable/disable closing after selecting an option
   * @default true
   * @type {Boolean}
   */
  closeOnSelect: {
    type: Boolean,
    default: true
  },
  /**
   * Function to interpolate the custom label
   * @default false
   * @type {Function}
   */
  customLabel: {
    type: Function,
    default: false
  },
  /**
   * Disable / Enable tagging
   * @default false
   * @type {Boolean}
   */
  taggable: {
    type: Boolean,
    default: false
  },
  /**
   * Callback function to run when attemting to add a tag
   * @default suitable for primitive values
   * @param {String} Tag string to build a tag
   * @type {Function}
   */
  onTag: {
    type: Function,
    default: function (tag) {
      this.options.push(tag)
      this.value.push(tag)
    }
  },
  /**
   * String to show when highlighting a potential tag
   * @default 'Press enter to create a tag'
   * @type {String}
  */
  tagPlaceholder: {
    type: String,
    default: 'Press enter to create a tag'
  },
  /**
   * Number of allowed selected options. No limit if false.
   * @default False
   * @type {Number}
  */
  max: {
    type: Number,
    default: false
  }
}

// pointerMixin.js

props: {
  /**
   * Enable/disable highlighting of the pointed value.
   * @type {Boolean}
   * @default true
   */
  showPointer: {
    type: Boolean,
    default: true
  }
}

// Multiselect.vue

props: {
  /**
   * String to show when pointing to an option
   * @default 'Press enter to select'
   * @type {String}
   */
  selectLabel: {
    type: String,
    default: 'Press enter to select'
  },
  /**
   * String to show next to selected option
   * @default 'Selected'
   * @type {String}
  */
  selectedLabel: {
    type: String,
    default: 'Selected'
  },
  /**
   * String to show when pointing to an alredy selected option
   * @default 'Press enter to remove'
   * @type {String}
  */
  deselectLabel: {
    type: String,
    default: 'Press enter to remove'
  },
  /**
   * Decide whether to show pointer labels
   * @default true
   * @type {Boolean}
  */
  showLabels: {
    type: Boolean,
    default: true
  },
  /**
   * Label to look for in option Object
   * @default 'label'
   * @type {String}
   */
  limit: {
    type: Number,
    default: 99999
  },
  /**
   * Function that process the message shown when selected
   * elements pass the defined limit.
   * @default 'and * more'
   * @param {Int} count Number of elements more than limit
   * @type {Function}
   */
  limitText: {
    type: Function,
    default: count => `and ${count} more`
  }
}

Contributing

# serve with hot reload at localhost:8080
npm run dev

# lib distribution build with minification
npm run bundle

# build the docs into gh-pages
npm run docs

# run unit tests
npm run test

# run unit tests watch
npm run unit-watch

For detailed explanation on how things work, checkout the guide and docs for vue-loader.