Vue 3 Multiselect

## Sponsors

## About Vueform

Vueform is a comprehensive form builder for Vue.js that makes form development a breeze. It standardizes and handles the entire form building process, including: - a complete theming and templating system with **Tailwind support** (similar to @vueform libraries) - 25+ form elements with **multi-file uploads**, date pickers and rich text editor - element **nesting** and **repeating** - **50+ validators** with async, dependent and custom rules - **conditional logic** on element & form level - breaking forms into **steps** with **form wizard** - **dynamic** form rendering with **JSON** support - **translating** form content and global i18n support. Vueform [pre-release](https://vueform.com) is open for registration for the **first 100 developers** with **special discounts**. Learn more: [https://vueform.com](https://vueform.com) ## Other libraries * [@vueform/slider](https://github.com/vueform/slider) - Vue 3 slider component with multihandles, tooltips merging and formatting. * [@vueform/toggle](https://github.com/vueform/toggle) - Vue 3 toggle component with labels, custom slots and styling options. ## Multiselect features * Vue 2 & 3 support * No dependencies * 100% coverage * TypeScript support * ESM support * Single select options * Multiple select options * Tags * Option groups * Async options * Search & filtering * Custom slots * Events * CSS vars support * **Tailwind** & utility class support * Fully configurable * CSP compilant ## Sections * [Demo](#demo) * [Installation](#installation) * [Using with Vue 3](#using-with-vue-3) * [Using with Vue 2](#using-with-vue-2) * [Using with Nuxt.js](#using-with-nuxtjs) * [Support](#support) * [Configuration](#configuration) * [Basic props](#basic-props) * [Advanced props](#advanced-props) * [API](#api) * [Events](#events) * [Slots](#slots) * [Styling](#styling) * [Styling with CSS vars](#styling-with-css-vars) * [Styling with Tailwind CSS](#styling-with-tailwind-css) * [Examples](#examples) * [Single select](#single-select) * [Multiselect with object options](#multiselect-with-object-options) * [Multiselect with disabled options](#multiselect-with-disabled-options) * [Multiselect with groups](#multiselect-with-groups) * [Tags with search, create and array of objects options](#tags-with-search-create-and-array-of-objects-options) * [Autocomplete with async options](#autocomplete-with-async-options) * [Tags with async options](#tags-with-async-options) * [Select with custom options slot](#select-with-custom-options-slot) * [Multiselect with custom label slot](#multiselect-with-custom-label-slot) * [Tags with custom tags slot](#tags-with-custom-tags-slot) * [License](#license) ## Demo Check out our demo. ## Installation ``` npm install @vueform/multiselect ``` ## Using with Vue 3 ``` vue ``` ## Using with Vue 2 When using Vue 2 install [@vue/composition-api](https://github.com/vuejs/composition-api#npm) via npm/yarn first: ``` bash npm i @vue/composition-api --save-dev ``` Then install the plugin for Vue: ``` js import Vue from 'vue' import VueCompositionAPI from '@vue/composition-api' Vue.use(VueCompositionAPI) ``` After that make sure to change the imported Multiselect module to: ``` js import Multiselect from '@vueform/multiselect/dist/multiselect.vue2.js' ``` ## Using with Nuxt.js First you need install [@nuxtjs/composition-api](https://composition-api.nuxtjs.org/getting-started/setup): ``` bash npm i @nuxtjs/composition-api --save ``` Then you need to enable it as a module in `nuxt.config.js`: ``` js { buildModules: [ '@nuxtjs/composition-api/module' ] } ``` After that make sure to change the imported module to Vue 2 version of Multiselect: ``` js import Multiselect from '@vueform/multiselect/dist/multiselect.vue2' ``` For more information on using `@nuxtjs/composition-api` read [their documentation](https://composition-api.nuxtjs.org/). ## Support Join our [Discord channel](https://discord.gg/WhX2nG6GTQ) or [open an issue](https://github.com/vueform/multiselect/issues). ## Configuration ### 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:
`[`
  `{`
    `[valueProp]: 1,`
    `[label]: 'v1',`
    `disabled:true\|false`
  `},`
  `//...`
`]`
- 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 properties that equal to `:valueProp`'s, `:trackBy`'s and `:label`'s value. | | **groups** | `boolean` | `false` | Whether options should be groupped. Example:
`{`
  `groups: true,`
  `options: [`
    `{`
      `[groupLabel]: 'Group label',`
      `[groupOptions]: {options},`
      `disabled: true\|false,`
    `}`
    `//...`
  `]`
`}`
The `{options}` should equal to regular `options` definition. | | **groupLabel** | `string` | `label` | The name of the property that contains the label of a group when `options` are provided in group format and `groups` is `true`. | | **groupOptions** | `string` | `options` | The name of the property that contains the options of a group when `options` are provided in group format and `groups` is `true`. | | **groupSelect** | `boolean` | `true` | Whether groups can be selected when using `multiple` or `tags` mode. | | **groupHideEmpty** | `boolean` | `false` | Whether groups that have no `options` by default should be hidden. | | **required** | `boolean` | `false` | Whether the HTML5 required attribute should be used for multiselect (using an invisible fake input). | | **searchable** | `boolean` | `false` | Whether the options should be searchable. | | **valueProp** | `string` | `'value'` | If you provide an array of objects as `options` this property should be used as the value of the option. | | **trackBy** | `string` | `undefined` | The name of the property that should be searched when `searchable` is `true` and an array of objects are provided as `options`. If left `undefined` the `label` prop will be used instead. | | **label** | `string` | `'label'` | If you provide an array of objects as `options` the value of this property will be displayed as selected option. | | **placeholder** | `string` | `null` | The text that should be displayed before any option is selected. | | **multipleLabel** | `function` | | A function that returns the label to be displayed for selected options 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 for the user (API can still be used programmatically). | | **inputType** | `string` | `text` | The `type` attribute of the search input. | | **autocomplete** | `string` | `undefined` | The `autocomplete` attribute of the search input. | | **max** | `number` | `-1` | The maximum number of options that **can be selected** when using `multiple` or `tags` mode. If `-1` the number of options won't be limited. | | **limit** | `number` | `-1` | The maximum number of options that **should be displayed**. If `-1` the number of options 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 the caret symbol on the right. | | **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 displayed when there are no search results. | | **openDirection** | `string` | `bottom` | Whether the option list should be displayed above or below the multiselect. Possible values: `top\|bottom` | | **strict** | `boolean` | `true` | Whether should regard accents/diacritics in search. | | **classes** | `object` | | An object of class names that gets merged with the default values. Default: `{`
  `container: 'multiselect',`
  `containerDisabled: 'is-disabled',`
  `containerOpen: 'is-open',`
  `containerOpenTop: 'is-open-top',`
  `containerActive: 'is-active',`
  `singleLabel: 'multiselect-single-label',`
  `singleLabelText: 'multiselect-single-label-text',`
  `multipleLabel: 'multiselect-multiple-label',`
  `search: 'multiselect-search',`
  `tags: 'multiselect-tags',`
  `tag: 'multiselect-tag',`
  `tagDisabled: 'is-disabled',`
  `tagRemove: 'multiselect-tag-remove',`
  `tagRemoveIcon: 'multiselect-tag-remove-icon',`
  `tagsSearchWrapper: 'multiselect-tags-search-wrapper',`
  `tagsSearch: 'multiselect-tags-search',`
  `tagsSearchCopy: 'multiselect-tags-search-copy',`
  `placeholder: 'multiselect-placeholder',`
  `caret: 'multiselect-caret',`
  `caretOpen: 'is-open',`
  `clear: 'multiselect-clear',`
  `clearIcon: 'multiselect-clear-icon',`
  `spinner: 'multiselect-spinner',`
  `dropdown: 'multiselect-dropdown',`
  `dropdownTop: 'is-top',`
  `dropdownHidden: 'is-hidden',`
  `options: 'multiselect-options',`
  `optionsTop: 'is-top',`
  `group: 'multiselect-group',`
  `groupLabel: 'multiselect-group-label',`
  `groupLabelPointable: 'is-pointable',`
  `groupLabelPointed: 'is-pointed',`
  `groupLabelSelected: 'is-selected',`
  `groupLabelDisabled: 'is-disabled',`
  `groupLabelSelectedPointed: 'is-selected is-pointed',`
  `groupLabelSelectedDisabled: 'is-selected is-disabled',`
  `groupOptions: 'multiselect-group-options',`
  `option: 'multiselect-option',`
  `optionPointed: 'is-pointed',`
  `optionSelected: 'is-selected',`
  `optionDisabled: 'is-disabled',`
  `optionSelectedPointed: 'is-selected is-pointed',`
  `optionSelectedDisabled: 'is-selected is-disabled',`
  `noOptions: 'multiselect-no-options',`
  `noResults: 'multiselect-no-results',`
  `fakeInput: 'multiselect-fake-input',`
  `spacer: 'multiselect-spacer'`
`}` |

### Advanced Props | Name | Type | Default | Description | | --- | --- | --- | --- | | **canDeselect** | `boolean` | `true` | Whether a selected option can be deselected when using `single` mode. | | **canClear** | `boolean` | `true` | Whether option(s) can be cleared. | | **clearOnSearch** | `boolean` | `false` | Whether the option list should be cleared when a new character is typed before loading new options list, when using async options. | | **clearOnSelect** | `boolean` | `true` | Whether the option list should be cleared upon selecting an option when using async options. | | **closeOnSelect** | `boolean` | `true` | Whether the option list should be hidden upon selecting an option. | | **delay** | `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** | `boolean` | `true` | Whether option list should be filtered by search query. This may be set to `false` if you are handling filtering manually when returning async options. | | **minChars** | `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** | `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** | `boolean` | `true` | **Deprecated 2.3.0: use `appendNewOption` instead.**
Whether it 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** | `boolean` | `false` | **Deprecated 2.3.0: use `createOption` instead.**
Whether it should allow creating new tags based on search query when using `tags` mode. | | **addTagOn** | `array` | `['enter']` | **Deprecated 2.3.0: use `addOptionOn` instead.**
The list of keys that creates a new tag while typing in the search field when having `createTag` enabled. Possible values: `'enter'\|'space'\|'tab'\|';'\|','`. | | **appendNewOption** | `boolean` | `true` | Whether it should append new option automatically to option list when `searchable` and `createTag` are enabled. If set to `false` you need to take care of appending a new option to the provided `:options` list upon `@option` event. | | **createOption** | `boolean` | `false` | Whether it should allow creating new options based on search query when `searchable` is enabled. | | **addOptionOn** | `array` | `['enter']` | The list of keys that creates a new option while typing in the search field when having `createOption` enabled. Possible values: `'enter'\|'space'\|'tab'\|';'\|','`. | | **hideSelected** | `boolean` | `true` | Whether selected options should be excluded from the option list when using `multiple` or `tags` mode. | | **showOptions** | `boolean` | `true` | Whether option list should be displayed. Can be used to create free-typed tags. | | **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'}`
`]` | | **attrs** | `object` | `{}` | HTML attributes to add to the `input` field when `search` is enabled. | | **nativeSupport** | `boolean` | `false` | Whether hidden input fields should be appended to achieve native data handling. | ## API | Name | Params | Description | | --- | --- | --- | | **open** | | Opens the options list. | | **close** | | Closes the options list. | | **select** | `option` | Selects an option based on its value. | | **deselect** | `option` | Deselects an option based on its value. | | **remove** | `option` | Alias for `deselect`. | | **selectAll** | | Selects all options if mode is `tags` or `multiple`. | | **clear** | | Deselects all selected options. | | **clearSearch** | | Clears current search query. | | **refreshOptions** | `callback` | Refreshes async options list. | | **setPointer** | `option` | Points an option based on its value. | To access API use `ref` on `Multiselect` component: ``` html ``` ``` js // eg: mounted() { this.$refs.multiselect.open() } ``` To programmatically open and focus the multiselect, call `focus()` on the element: ```js mounted() { this.$refs.multiselect.$el.focus() } ``` ## 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` | **Deprecated 2.3.0: use `@option` instead**. Emitted after enter is hit when a new tag is being created. | | **@option** | `query` | Emitted after enter is hit when a new option is being created. | | **@clear** | | Emitted when the options are cleared. | | **@paste** | `Event` | Emitted when value is pasted into the search field. | ## Slots | Slot | Attributes | Description | | --- | --- | --- | | **placeholder** | | Rendered as placeholder when the multiselect does not have value and `placeholder` prop is defined. | | **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`. | | **grouplabel** | `group` | Renders an option group label. | | **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, handleTagRemove, disabled` | Renders a tag when using `tags` mode. When `disabled` the remove icon should not be displayed. The `handleTagRemove` prop should be used to trigger the removal of the tag. | | **caret** | | Renders a small triangle on the right side of the multiselect. | | **clear** | `clear` | Renders a remove icon if the multiselect has any value. The `clear` method should be used on `mousedown` event. | | **spinner** | | Renders a loader icon when async options are being fetched. | > Note: we don't use camelCase because they are [normalized back to lowercase](https://github.com/vuejs/vue/issues/9449#issuecomment-461170017) when written in DOM. ## Styling ### Styling with CSS vars The following CSS variables can be used to customize multiselect when using `default.css`: ``` css --ms-font-size: 1rem; --ms-line-height: 1.375; --ms-bg: #FFFFFF; --ms-bg-disabled: #F3F4F6; --ms-border-color: #D1D5DB; --ms-border-width: 1px; --ms-radius: 4px; --ms-py: 0.5rem; --ms-px: 0.875rem; --ms-ring-width: 3px; --ms-ring-color: #10B98130; --ms-placeholder-color: #9CA3AF; --ms-max-height: 10rem; --ms-spinner-color: #10B981; --ms-caret-color: #999999; --ms-clear-color: #999999; --ms-clear-color-hover: #000000; --ms-tag-font-size: 0.875rem; --ms-tag-line-height: 1.25rem; --ms-tag-font-weight: 600; --ms-tag-bg: #10B981; --ms-tag-bg-disabled: #9CA3AF; --ms-tag-color: #FFFFFF; --ms-tag-color-disabled: #FFFFFF; --ms-tag-radius: 4px; --ms-tag-py: 0.125rem; --ms-tag-px: 0.5rem; --ms-tag-my: 0.25rem; --ms-tag-mx: 0.25rem; --ms-tag-remove-radius: 4px; --ms-tag-remove-py: 0.25rem; --ms-tag-remove-px: 0.25rem; --ms-tag-remove-my: 0rem; --ms-tag-remove-mx: 0.125rem; --ms-dropdown-bg: #FFFFFF; --ms-dropdown-border-color: #D1D5DB; --ms-dropdown-border-width: 1px; --ms-dropdown-radius: 4px; --ms-group-label-py: 0.3rem; --ms-group-label-px: 0.75rem; --ms-group-label-line-height: 1.375; --ms-group-label-bg: #E5E7EB; --ms-group-label-color: #374151; --ms-group-label-bg-pointed: #D1D5DB; --ms-group-label-color-pointed: #374151; --ms-group-label-bg-disabled: #F3F4F6; --ms-group-label-color-disabled: #D1D5DB; --ms-group-label-bg-selected: #059669; --ms-group-label-color-selected: #FFFFFF; --ms-group-label-bg-selected-pointed: #0c9e70; --ms-group-label-color-selected-pointed: #FFFFFF; --ms-group-label-bg-selected-disabled: #75cfb1; --ms-group-label-color-selected-disabled: #D1FAE5; --ms-option-font-size: 1rem; --ms-option-line-height: 1.375; --ms-option-bg-pointed: #FFFFFF; --ms-option-color-pointed: #1F2937; --ms-option-bg-selected: #10B981; --ms-option-color-selected: #FFFFFF; --ms-option-bg-disabled: #FFFFFF; --ms-option-color-disabled: #D1D5DB; --ms-option-bg-selected-pointed: #26C08E; --ms-option-color-selected-pointed: #FFFFFF; --ms-option-bg-selected-disabled: #FFFFFF; --ms-option-color-selected-disabled: #D1FAE5; --ms-option-py: 0.5rem; --ms-option-px: 0.75rem; --ms-empty-color: #4B5563; ``` Override them globally: ``` css :root { --ms-tag-bg: #059669; --ms-tag-color: #D1FAE5; --ms-tag-radius: 9999px; --ms-tag-font-weight: 400; } ``` Or on an instance level: ``` vue ``` ``` css .multiselect-green { --ms-tag-bg: #D1FAE5; --ms-tag-color: #059669; } .multiselect-blue { --ms-tag-bg: #DBEAFE; --ms-tag-color: #2563EB; } ``` ### Styling with Tailwind CSS To use `Multiselect` with Tailwind CSS first you need to add background images to `tailwind.config.js`: ``` js // tailwind.config.js const svgToDataUri = require('mini-svg-data-uri') module.exports = { theme: { extend: { backgroundImage: (theme) => ({ 'multiselect-caret': `url("${svgToDataUri( ``, )}")`, 'multiselect-spinner': `url("${svgToDataUri( ``, )}")`, 'multiselect-remove': `url("${svgToDataUri( ``, )}")`, }) }, } } ``` Then you need to import `themes/tailwind.scss` to you main component: ``` vue ``` #### Using `:classes` prop Alternatively you can define class names directly by passing them to the `Multiselect` component via `classes` property. When using this approach you don't need to import `tailwind.scss`. Here's a default styling for Tailwind CSS (the same included in `tailwind.scss`): ``` vue ``` Certain classes has different states which are merged to the base class when the state is active. For example `dropdown` will be merged with `dropdownTop` when `open-direction: 'top'` resulting in the following classes: ```absolute -left-px -right-px bottom-0 transform translate-y-full border border-gray-300 -mt-px overflow-y-scroll z-50 bg-white flex flex-col rounded-b -translate-y-full top-px bottom-auto flex-col-reverse rounded-b-none rounded-t``` The same is true for `container`, `tag`, `options`, `groupLabel` and `option` classes. In case you need to override the same type of utility you might use [@neojp/tailwind-important-variant](https://www.npmjs.com/package/@neojp/tailwindcss-important-variant) for eg. `bg-green-500!`. ## Examples * [Single select](#single-select) * [Multiselect with object options](#multiselect-with-object-options) * [Multiselect with disabled options](#multiselect-with-disabled-options) * [Multiselect with groups](#multiselect-with-groups) * [Tags with search, create and array of objects options](#tags-with-search-create-and-array-of-objects-options) * [Autocomplete with async options](#autocomplete-with-async-options) * [Tags with async options](#tags-with-async-options) * [Select with custom options slot](#select-with-custom-options-slot) * [Multiselect with custom label slot](#multiselect-with-custom-label-slot) * [Tags with custom tags slot](#tags-with-custom-tags-slot) ### Single select ``` vue ``` JSFiddle - Example #1 ### Multiselect with object options ``` vue ``` JSFiddle - Example #2 ### Multiselect with disabled options ``` vue ``` JSFiddle - Example #3 ### Multiselect with groups ``` vue ``` JSFiddle - Example #4 ### Tags with search, create and array of objects options ``` vue ``` JSFiddle - Example #5 ### Autocomplete with async options ``` vue ``` JSFiddle - Example #6 ### Tags with async options ``` vue ``` JSFiddle - Example #7 ### Select with custom options slot ``` vue ``` JSFiddle - Example #8 ### Multiselect with custom label slot ``` vue ``` JSFiddle - Example #9 ### Tags with custom tags slot ``` vue ``` JSFiddle - Example #10 ## License [MIT](https://github.com/vueform/multiselect/blob/main/LICENSE.md)