tessl/npm-vue-multiselect
Vue 3 compatible multiselect component with advanced selection, search, tagging, and grouping capabilities
—
Pending
basic-selection.mddocs/
Basic Selection
Core single and multiple selection functionality with v-model support, handling objects, arrays, strings, and numbers as option values.
Capabilities
Single Selection
Default selection mode where users can select one option at a time.
/**
* Single selection component props
*/
interface SingleSelectionProps {
/** Current selected value, supports any type */
modelValue?: any;
/** Array of available options */
options: any[];
/** Property name for tracking object equality (default: 'id') */
trackBy?: string;
/** Property name for display labels in objects (default: 'label') */
label?: string;
/** Placeholder text when no option is selected */
placeholder?: string;
/** Disable the entire component */
disabled?: boolean;
/** Allow clearing the selection */
allowEmpty?: boolean;
}Usage Example:
<template>
<VueMultiselect
v-model="selectedUser"
:options="users"
track-by="id"
label="name"
placeholder="Select a user">
</VueMultiselect>
</template>
<script>
export default {
data() {
return {
selectedUser: null,
users: [
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' }
]
}
}
}
</script>Multiple Selection
Allows selection of multiple options simultaneously, with v-model binding to an array.
/**
* Multiple selection component props
*/
interface MultipleSelectionProps {
/** Array of currently selected values */
modelValue?: any[];
/** Array of available options */
options: any[];
/** Enable multiple selection mode */
multiple: true;
/** Property name for tracking object equality */
trackBy?: string;
/** Property name for display labels in objects */
label?: string;
/** Maximum number of selections allowed (0 = unlimited) */
max?: number | boolean;
/** Disable the entire component */
disabled?: boolean;
}Usage Example:
<template>
<VueMultiselect
v-model="selectedTags"
:options="availableTags"
:multiple="true"
:max="5"
track-by="id"
label="name"
placeholder="Select tags">
</VueMultiselect>
</template>
<script>
export default {
data() {
return {
selectedTags: [],
availableTags: [
{ id: 1, name: 'Vue.js' },
{ id: 2, name: 'JavaScript' },
{ id: 3, name: 'TypeScript' }
]
}
}
}
</script>String and Number Options
Support for simple string and number arrays without object structures.
/**
* Simple value selection props
*/
interface SimpleValueProps {
/** String, number, or array of strings/numbers */
modelValue?: string | number | (string | number)[];
/** Array of strings or numbers */
options: (string | number)[];
/** Enable multiple selection for arrays */
multiple?: boolean;
/** Placeholder text */
placeholder?: string;
}Usage Example:
<template>
<VueMultiselect
v-model="selectedColors"
:options="colors"
:multiple="true"
placeholder="Choose colors">
</VueMultiselect>
</template>
<script>
export default {
data() {
return {
selectedColors: [],
colors: ['Red', 'Green', 'Blue', 'Yellow', 'Purple']
}
}
}
</script>Value Comparison and Tracking
Controls how options are compared for equality and selection state.
/**
* Value tracking configuration
*/
interface ValueTrackingProps {
/**
* Property name for comparing objects (default: 'id')
* Used to determine if two objects represent the same option
*/
trackBy?: string;
/**
* Property name for display text (default: 'label')
* Used to extract the display value from objects
*/
label?: string;
/**
* Custom function to generate display labels
* @param option - The option object
* @param label - The label property name
* @returns Custom formatted string
*/
customLabel?: (option: any, label: string) => string;
}Usage Example:
<template>
<VueMultiselect
v-model="selectedProduct"
:options="products"
track-by="sku"
label="title"
:custom-label="formatProductLabel">
</VueMultiselect>
</template>
<script>
export default {
data() {
return {
selectedProduct: null,
products: [
{ sku: 'ABC123', title: 'Laptop', price: 999.99 },
{ sku: 'DEF456', title: 'Mouse', price: 29.99 }
]
}
},
methods: {
formatProductLabel({ title, price }) {
return `${title} - $${price}`;
}
}
}
</script>Selection Events
Events emitted during selection operations.
/**
* Selection-related events
*/
interface SelectionEvents {
/** Emitted when selection changes (v-model compatibility) */
'@update:modelValue': (value: any) => void;
/** Emitted when an option is selected */
'@select': (selectedOption: any, id: string | number) => void;
/** Emitted when an option is removed from selection */
'@remove': (removedOption: any, id: string | number) => void;
/** Emitted when dropdown opens */
'@open': (id: string | number) => void;
/** Emitted when dropdown closes */
'@close': (value: any, id: string | number) => void;
}Selection State Management
Methods for programmatically controlling selection state.
/**
* Component methods for selection control
*/
interface SelectionMethods {
/** Programmatically open the dropdown */
activate(): void;
/** Programmatically close the dropdown */
deactivate(): void;
/** Check if a specific option is currently selected */
isSelected(option: any): boolean;
/** Select or deselect an option programmatically */
select(option: any, key?: string): void;
/** Remove an option from current selection */
removeElement(option: any, shouldClose?: boolean): void;
/** Get the current selection in the correct format */
getValue(): any;
}Form Integration
HTML Form Support
Integration with HTML forms and validation.
/**
* Form integration props
*/
interface FormIntegrationProps {
/** HTML name attribute for form submission */
name?: string;
/** HTML required attribute - validates when no selection */
required?: boolean;
/** HTML tabindex for keyboard navigation */
tabindex?: number;
}Usage Example:
<template>
<form @submit="handleSubmit">
<VueMultiselect
v-model="selectedCategory"
:options="categories"
name="category"
:required="true"
:tabindex="1"
placeholder="Select category">
</VueMultiselect>
<button type="submit">Submit</button>
</form>
</template>Vuex Integration
Works seamlessly with Vuex store patterns.
<template>
<VueMultiselect
:model-value="selectedItems"
@update:model-value="updateSelection"
:options="availableItems">
</VueMultiselect>
</template>
<script>
import { mapState, mapMutations } from 'vuex'
export default {
computed: {
...mapState(['selectedItems', 'availableItems'])
},
methods: {
...mapMutations(['updateSelection'])
}
}
</script>Install with Tessl CLI
npx tessl i tessl/npm-vue-multiselect