Introduction
Vue multi select is a lightweight, multi/single select fast and fully custom.
Vue multi select provides basic things like groups, research, buttons to select/deselect all many customisation to adapt the best way to your application.
Installation
Dependencies
- required: Vuejs >= 2.x
Install
Clone the repo
github or
npm install vue-multi-select --save
Include the file in your app import vueMultiSelect from
import vueMultiSelect from 'vue-multi-select';
import 'vue-multi-select/dist/lib/vue-multi-select.css';
What's new
4.6.0
Set a props for label when empty data4.5.0
Set possible to open manually4.4.1
Fix labelName for default slot4.4.0
Set possible to use slot-scope for options. renderTemplate is no more Supported4.3.0
Add disabledUnSelect popoverClass as props4.2.0
Add btnClass popoverClass as props4.1.1
Build lib4.1.0
Use v-html to display button4.0.0
Use vue-cli to bundle3.16.0
Add open/close events3.15.0
Use a function to render btnLabel3.14.1
Fix event triggered 2 times in single select3.14.0
Set possible to disable vueMultiSelect3.13.1
Fix doc about css import3.13.0
Set position custom3.12.1
Small change about way to render name3.12.0
Use v-html to render options3.11.1
Fix button for simple array
3.11.0
Set up an historic mode
3.10.0
Remove default select all and update a little some css
3.9.1
Remove reloadInit and for manual reload. Now just update v-model, vue-multi-select will reload automatically
General
Directive must be call like that in Html
<multi-select></multi-select>
Props for vue-multi-select :
| Params | Type | Description | Default |
|---|---|---|---|
| options | Object | Permit to params most the options of the multi Select | {} |
| filters | Array | Permit to add some filters in the vueMultiSelect's input | [] |
| selectOptions | Array | Variables who contains values for the select | [] |
| eventName | String | eventName Name for the event triggered by the vue-multi-select default is selectionChanged (deprecated, use v-model or a watch) | 'selectionChanged' |
| v-model | Array | Variables who contains values selected | - |
| search | Boolean | hide/show search bar (search isn't case sensitive) | False |
| searchPlaceholder | String | Change placeholder of searchBar | 'Search...' |
| historyButton | Boolean | Display the button to use previous values selected | false |
| historyButtonText | String | Label for previous button | '↶'' |
| position | String | Where to display options, top/bottom-left/right | 'top-bottom' |
| disabled | Boolean | Disable button | False |
| disabledUnSelect | Boolean | To disable the possibility to unselect an option (only in singleSelect) | false |
| emptyTabText | String | Label when empty tab | 'No data' |
Events for vue-multi-select :
| name | params | Description |
|---|---|---|
| selectionChanged | selected values | triggered when an option is selected (the name can be changed with props eventName) |
| open | - | triggered when the vue-multi-select open |
| close | - | triggered when the vue-multi-select close |
options
This variable contains params to setup the vue-multi-select.
Props for vue-multi-select :
| Params | Type | Default | Description |
|---|---|---|---|
| btnLabel | Function | () => ('multi-select') |
Label on the button |
| btnClass | String | '' |
css class who apply on the button |
| popoverClass | String | '' |
css class who apply on the popover |
| cssSelected | Function | (option) => option['selected'] ?
{'background-color': '#b4b4b4'} : '' |
Css passed to value selected |
| groups | Boolean | false |
Display or not groups selection |
| multi | Boolean | false |
Set single or multiple selection |
| labelList | String | 'list' |
Name Attributes for list |
| labelName | String | 'name' |
Name Attributes for value to display |
| labelValue | String | labelName |
Attributes for value to compare them |
| labelSelected | String | 'selected' |
Name Attributes for value to display |
| labelDisabled | String | 'disabled' |
Name Attributes for value to disable |
| groupName | String | 'name' |
Name Attributes for groups to display |
Filters
filters to apply to select many options
nameAll
Name displayed when all elements respect the condition
nameNotAll
Name displayed when all elements don't respect the condition
func
The function (must return true or false) who permit to test if
the element respect a condition
const filters = [];
filters.push({
/* label when want to select all elements who
answer yes to the function */
nameAll: 'Select all',
nameNotAll: 'Deselect all',
/* label when want to deselect all elements
who answer yes to the function */
func(elem) {
return true;
}
});
// Second exemple to select all elements who contain 2
filters.push({
nameAll: 'Select all elements with 2',
nameNotAll: 'Deselect all elements with 2',
func(elem) {
return elem.name.indexOf('2') !== -1;
},
});
selectOptions
elements to select/deselect
if options.groups set to default/false
just use an Array of objects
[{name: 1},{name: 2}, ...]
or of strings
['Germany', 'England', ...]
If options.groups set to true
data.name group name displayed, can be changed with tabName
data.list Name of the attributes for the array of
elements, can be changed with listName
it can'be an array of string or an array of objects
data.list[x].name Name of the attributes to display one elements,
can be changed with labelName
const data = [{
name: 'choice 1',
// Can be changed with tabName in options
list: [ // Can be changed with listName in options
{name: 'choice 1'},
// Mame can be changed with labelName in options
{name: 'choice 2'},
{name: 'choice 3'},
{name: 'choice 4'},
{name: 'choice 5'},
]
}, {
name: 'choice 10',
// Can be changed with tabName in options
list: [
{name: 'choice 11'},
// Mame can be changed with labelName in options
{name: 'choice 12'},
{name: 'choice 13'},
{name: 'choice 14'},
{name: 'choice 15'},
]
}]
eventName
Variable containing the name of the event who will be launch when vue-multi-select value change
Example of function to get data
const event = (values) => {
this.values = values;
}
Each value selected is push in this Array.
When a value is unselect, he is splice fron the Array
[ {name: 'choice 1'},
{name: 'choice 11'}]
// In the case we selected choice 1 and choice 11
A simple vue-multi-select with slot-scope
values selected. Each value selected is push in this Array.
When a value is unselect, he is splice fron the Array
<template>
<div>
<vue-multi-select
ref="multiSelect"
v-model="values"
search
historyButton
:options="options"
:filters="filters"
:btnLabel="btnLabel"
@open="open"
@close="close"
:selectOptions="data">
<template v-slot:option="{option}">
<input type="checkbox" :checked="option.selected"/>
<span>{{option.name}}</span>
</template>
</vue-multi-select>
<button
@click="openManually">
Open manually
</button>
</div>
</template>
<script>
import vueMultiSelect from 'vue-multi-select';
import
'vue-multi-select/dist/lib/vue-multi-select.css';
export default {
data() {
return {
btnLabel: values => `A simple vue multi select (${values.length})`
name: 'first group',
values: [],
data: [{
name: 'first group',
list: [
{ name: '0' },
{ name: '2' },
{ name: '3' },
{ name: '8' },
{ name: '9' },
{ name: '11' },
{ name: '13' },
{ name: '14' },
{ name: '15' },
{ name: '18' },
],
}, {
name: 'second group',
list: [
{ name: '21' },
{ name: '22' },
{ name: '24' },
{ name: '27' },
{ name: '28' },
{ name: '29' },
{ name: '31' },
{ name: '33' },
{ name: '35' },
{ name: '39' },
],
}],
filters: [{
nameAll: 'Select all',
nameNotAll: 'Deselect all',
func() {
return true;
},
}, {
nameAll: 'select <= 10',
nameNotAll: 'Deselect <= 10',
func(elem) {
return elem.name <= 10;
},
}, {
nameAll: 'Select contains 2',
nameNotAll: 'Deselect contains 2',
func(elem) {
return elem.name.indexOf('2') !== -1;
},
}],
options: {
multi: true,
groups: true,
},
};
},
methods: {
openManually() {
this.$refs.multiSelect.openMultiSelect();
},
open() {
console.log('open');
},
close() {
console.log('close');
},
},
components: {
vueMultiSelect,
},
};
</script>
{{example1.values}}
A single Select with no groups
<template>
<div>
<vue-multi-select
v-model="values"
:btnLabel="btnLabel"
search
historyButton
:selectOptions="data" />
</div>
</template>
<script>
import vueMultiSelect from 'vue-multi-select';
import
'vue-multi-select/dist/lib/vue-multi-select.css';
export default {
data() {
return {
btnLabel: values =>values.length 0 ? values[0].name : 'Select ...',
name: 'first group',
values: [],
data: [
{ name: '0' },
{ name: '2' },
{ name: '3' },
{ name: '8' },
{ name: '9' },
{ name: '11' },
{ name: '13' },
{ name: '14' },
{ name: '15' },
{ name: '18' },
],
};
},
methods: {
},
components: {
vueMultiSelect,
},
};
</script>
{{example2.values}}
A custom multi select
if the labelSelected
and cssLabel
are changed don't forget to update
option['selected'] in
cssLabel with the labelSelected value
It's possible to disable some value with attributes disabled to true
(it's possible to change the key with options.labelDisabled)
<template>
<div>
<vue-multi-select
v-model="values"
search
historyButton
:filters="filters"
:options="options"
:selectOptions="data"/>
<button
@click="reloadFunction" >
Change v-model
</button>
</div>
</template>
<script>
import vueMultiSelect from 'vue-multi-select';
import
'vue-multi-select/dist/lib/vue-multi-select.css';
export default {
data() {
return {
name: 'first group',
values: [
{ label: '2' },
{ label: '3' },
],
data: [{
title: 'part one',
elements: [
{ label: '0', disabled: true },
{ label: '2' },
{ label: '3' },
{ label: '8' },
{ label: '9' },
{ label: '11' },
{ label: '13' },
{ label: '14' },
{ label: '15' },
{ label: '18' },
],
}, {
title: 'part two',
elements: [
{ label: '23' },
{ label: '25' },
{ label: '31' },
{ label: '42' },
{ label: '56' },
{ label: '76' },
{ label: '82' },
{ label: '42' },
{ label: '13' },
{ label: '21' },
],
}],
filters: [{
nameAll: 'Select all',
nameNotAll: 'Deselect all',
func() {
return true;
},
}],
options: {
multi: true,
groups: true,
labelName: 'label',
labelList: 'elements',
groupName: 'title',
cssSelected: option =>
(option.selected ?
{ 'background-color':
'#5764c6' } :
''),
},
};
},
methods: {
reloadFunction() {
this.values = [
{ label: '2' },
{ label: '3' },
];
},
},
components: {
vueMultiSelect,
},
};
</script>
{{example3.values}}
A multi select with array
list of data can be an array
<template>
<div>
<vue-multi-select
v-model="values"
search
historyButton
:filters="filters"
:position="position"
:options="options"
:selectOptions="data" />
<button
@click="reloadFunction">
Change v-model
</button>
</div>
</template>
<script>
import vue-multiSelect from 'vue-multi-select';
import
'vue-multi-select/dist/lib/vue-multi-select.css';
export default {
data() {
return {
name: 'first group',
values: [
'0',
'2',
],
data: [{
title: 'part one',
elements: [
'0',
'2',
'3',
'8',
'9',
'11',
'13',
'14',
'15',
'18',
],
}, {
title: 'part two',
elements: [
'23',
'25',
'31',
'42',
'56',
'76',
'82',
'42',
'13',
'21',
],
}],
filters: [{
nameAll: 'Select all',
nameNotAll: 'Deselect all',
func() {
return true;
},
}],
position: 'top-right',
options: {
multi: true,
groups: true,
labelList: 'elements',
groupName: 'title',
cssSelected: option =>
(option.selected ?
{ 'background-color':
'#5764c6' } :
''),
},
};
},
methods: {
reloadFunction() {
this.values = [
'2',
'3',
];
},
},
components: {
vueMultiSelect,
},
};
</script>
{{example4.values}}