0
# Vue Multiselect
1

2
Vue Multiselect is a comprehensive Vue 3 compatible multiselect component library that provides advanced selection capabilities for web applications. It offers multiple selection modes including single select, multiple select, tagging, and dropdown functionality with built-in search and filtering capabilities.
3

4
## Package Information
5

6
- **Package Name**: vue-multiselect
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install vue-multiselect`
10

11
## Core Imports
12

13
```javascript
14
import VueMultiselect from 'vue-multiselect'
15
```
16

17
Named imports:
18

19
```javascript
20
import { Multiselect, multiselectMixin, pointerMixin } from 'vue-multiselect'
21
```
22

23
## Basic Usage
24

25
```vue
26
<template>
27
  <div>
28
    <VueMultiselect
29
      v-model="selected"
30
      :options="options"
31
      placeholder="Select option"
32
      label="name"
33
      track-by="id">
34
    </VueMultiselect>
35
  </div>
36
</template>
37

38
<script>
39
import VueMultiselect from 'vue-multiselect'
40

41
export default {
42
  components: { VueMultiselect },
43
  data() {
44
    return {
45
      selected: null,
46
      options: [
47
        { id: 1, name: 'Option 1' },
48
        { id: 2, name: 'Option 2' },
49
        { id: 3, name: 'Option 3' }
50
      ]
51
    }
52
  }
53
}
54
</script>
55

56
<style src="vue-multiselect/dist/vue-multiselect.css"></style>
57
```
58

59
## Architecture
60

61
Vue Multiselect is built around several key components:
62

63
- **Main Component**: `Multiselect` Vue component providing the complete UI and functionality
64
- **Mixin System**: Logic separated into `multiselectMixin` and `pointerMixin` for reusability
65
- **Type Safety**: Full TypeScript definitions for all props, events, and methods
66
- **Extensibility**: Comprehensive slot system for custom rendering of all UI elements
67
- **Performance**: Optimized for large option lists with virtualization and lazy loading support
68

69
### Mixin System
70

71
Vue Multiselect uses a modular mixin architecture to separate concerns:
72

73
**multiselectMixin** - Core functionality including:
74
- Option selection and deselection logic
75
- Search and filtering capabilities
76
- Tagging and async option support
77
- Group option handling
78
- Value management and v-model integration
79

80
**pointerMixin** - Navigation and highlighting including:
81
- Keyboard navigation (arrow keys, enter, escape)
82
- Option pointer/highlight management
83
- Scroll position tracking
84
- Focus management
85

86
### Using Mixins
87

88
```typescript { .api }
89
// Import mixins for custom components
90
import { multiselectMixin, pointerMixin } from 'vue-multiselect';
91

92
// Use in custom Vue component
93
export default {
94
  mixins: [multiselectMixin, pointerMixin],
95
  // Your custom implementation
96
}
97
```
98

99
## Capabilities
100

101
### Basic Selection
102

103
Core single and multiple selection functionality with v-model support. Handles objects, arrays, strings, and numbers as option values.
104

105
```typescript { .api }
106
// Component props for basic selection
107
interface BasicSelectionProps {
108
  modelValue?: any | any[];
109
  options: any[];
110
  multiple?: boolean;
111
  trackBy?: string;
112
  label?: string;
113
  placeholder?: string;
114
  disabled?: boolean;
115
}
116
```
117

118
[Basic Selection](./basic-selection.md)
119

120
### Search and Filtering
121

122
Built-in search functionality with configurable filtering, custom search functions, and async option loading support.
123

124
```typescript { .api }
125
// Component props for search and filtering
126
interface SearchFilteringProps {
127
  searchable?: boolean;
128
  internalSearch?: boolean;
129
  clearOnSelect?: boolean;
130
  preserveSearch?: boolean;
131
  customLabel?: (option: any, label: string) => string;
132
  filteringSortFunc?: (a: any, b: any) => number;
133
}
134
```
135

136
[Search and Filtering](./search-filtering.md)
137

138
### Tagging Mode
139

140
Advanced tagging functionality allowing users to create new options dynamically through text input.
141

142
```typescript { .api }
143
// Component props for tagging
144
interface TaggingProps {
145
  taggable?: boolean;
146
  tagPlaceholder?: string;
147
  tagPosition?: 'top' | 'bottom';
148
}
149

150
// Component events for tagging
151
interface TaggingEvents {
152
  '@tag': (searchQuery: string, id: string | number) => void;
153
}
154
```
155

156
[Tagging Mode](./tagging-mode.md)
157

158
### Grouped Options
159

160
Support for hierarchical option structures with group selection capabilities and custom group rendering.
161

162
```typescript { .api }
163
// Component props for grouped options
164
interface GroupedOptionsProps {
165
  groupValues?: string;
166
  groupLabel?: string;
167
  groupSelect?: boolean;
168
}
169
```
170

171
[Grouped Options](./grouped-options.md)
172

173
### Advanced Configuration
174

175
Extensive configuration options for behavior control, limits, keyboard handling, and UI customization.
176

177
```typescript { .api }
178
// Component props for advanced configuration
179
interface AdvancedConfigProps {
180
  max?: number | boolean;
181
  limit?: number;
182
  limitText?: (count: number) => string;
183
  closeOnSelect?: boolean;
184
  clearOnSelect?: boolean;
185
  hideSelected?: boolean;
186
  allowEmpty?: boolean;
187
  resetAfter?: boolean;
188
  loading?: boolean;
189
}
190
```
191

192
[Advanced Configuration](./advanced-configuration.md)
193

194
### Custom Rendering
195

196
Comprehensive slot system enabling complete customization of all UI elements including options, tags, labels, and controls.
197

198
```typescript { .api }
199
// Component slots for custom rendering
200
interface CustomRenderingSlots {
201
  caret: { toggle: () => void };
202
  clear: { search: string };
203
  selection: { search: string; remove: (option: any) => void; values: any[]; isOpen: boolean };
204
  tag: { option: any; search: string; remove: (option: any) => void };
205
  option: { option: any; search: string; index: number };
206
  singleLabel: { option: any };
207
  noResult: { search: string };
208
  noOptions: {};
209
}
210
```
211

212
[Custom Rendering](./custom-rendering.md)
213

214
### Component Events
215

216
All component events for handling user interactions and state changes.
217

218
```typescript { .api }
219
// Component events
220
interface MultiselectEvents {
221
  /** Fired when dropdown opens */
222
  '@open': (id: string | number | null) => void;
223
  /** Fired when dropdown closes */
224
  '@close': (value: any, id: string | number | null) => void;
225
  /** Fired when option is selected */
226
  '@select': (option: any, id: string | number | null) => void;
227
  /** Fired when option is removed */
228
  '@remove': (option: any, id: string | number | null) => void;
229
  /** Fired when value changes (v-model) */
230
  '@update:modelValue': (newValue: any) => void;
231
  /** Fired when search input changes */
232
  '@search-change': (searchValue: string) => void;
233
  /** Fired when new tag is created */
234
  '@tag': (tagLabel: string, id: string | number | null) => void;
235
}
236
```
237

238
### Component Methods
239

240
Public methods that can be called via template refs.
241

242
```typescript { .api }
243
// Component methods accessible via template refs
244
interface MultiselectMethods {
245
  /** Opens the multiselect dropdown */
246
  activate(): void;
247
  /** Closes the multiselect dropdown */
248
  deactivate(): void;
249
  /** Toggles the dropdown open/closed state */
250
  toggle(): void;
251
  /** Add/remove given option from selected options */
252
  select(option: any, key?: string): void;
253
  /** Remove given option from selected options */
254
  removeElement(option: any, shouldClose?: boolean): void;
255
  /** Remove the last selected element */
256
  removeLastElement(): void;
257
  /** Updates the search value */
258
  updateSearch(query: string): void;
259
  /** Check if given element is selected */
260
  isSelected(option: any): boolean;
261
  /** Get display label for option */
262
  getOptionLabel(option: any): string;
263
}
264
```
265

266
### Component Slots
267

268
Complete slot system for custom UI rendering.
269

270
```typescript { .api }
271
// Component slots for custom rendering
272
interface MultiselectSlots {
273
  /** Override entire selection display */
274
  selection: { search: string; remove: (option: any) => void; values: any[]; isOpen: boolean };
275
  /** Override individual tag display */
276
  tag: { option: any; search: string; remove: (option: any) => void };
277
  /** Override single selection label */
278
  singleLabel: { option: any };
279
  /** Override placeholder content */
280
  placeholder: {};
281
  /** Override limit text when selections exceed limit */
282
  limit: {};
283
  /** Override individual option display */
284
  option: { option: any; search: string; index: number };
285
  /** Content before options list */
286
  beforeList: {};
287
  /** Content after options list */
288
  afterList: {};
289
  /** Message when search returns no results */
290
  noResult: { search: string };
291
  /** Message when no options available */
292
  noOptions: {};
293
  /** Message when max selections reached */
294
  maxElements: {};
295
  /** Override dropdown arrow/caret */
296
  caret: { toggle: () => void };
297
  /** Override clear button */
298
  clear: { search: string };
299
  /** Override loading spinner */
300
  loading: {};
301
}
302
```
303

304
## Types
305

306
```typescript { .api }
307
// Complete component props interface
308
interface MultiselectProps {
309
  // Core selection props
310
  modelValue?: any | any[];
311
  options: any[];
312
  multiple?: boolean;
313
  trackBy?: string;
314
  label?: string;
315
  placeholder?: string;
316
  disabled?: boolean;
317
  allowEmpty?: boolean;
318
  
319
  // Search and filtering props
320
  searchable?: boolean;
321
  internalSearch?: boolean;
322
  clearOnSelect?: boolean;
323
  preserveSearch?: boolean;
324
  customLabel?: (option: any, label: string) => string;
325
  filteringSortFunc?: (a: any, b: any) => number;
326
  
327
  // Tagging props
328
  taggable?: boolean;
329
  tagPlaceholder?: string;
330
  tagPosition?: 'top' | 'bottom';
331
  
332
  // Grouped options props
333
  groupValues?: string;
334
  groupLabel?: string;
335
  groupSelect?: boolean;
336
  
337
  // Advanced configuration props
338
  max?: number | boolean;
339
  limit?: number;
340
  limitText?: (count: number) => string;
341
  closeOnSelect?: boolean;
342
  hideSelected?: boolean;
343
  resetAfter?: boolean;
344
  loading?: boolean;
345
  optionsLimit?: number;
346
  blockKeys?: string[];
347
  preselectFirst?: boolean;
348
  preventAutofocus?: boolean;
349
  
350
  // Component-specific props
351
  name?: string;
352
  selectLabel?: string;
353
  selectGroupLabel?: string;
354
  selectedLabel?: string;
355
  deselectLabel?: string;
356
  deselectGroupLabel?: string;
357
  showLabels?: boolean;
358
  maxHeight?: number;
359
  spellcheck?: boolean;
360
  openDirection?: string;
361
  showNoOptions?: boolean;
362
  showNoResults?: boolean;
363
  tabindex?: number;
364
  required?: boolean;
365
  
366
  // Pointer/navigation props
367
  showPointer?: boolean;
368
  optionHeight?: number;
369
  
370
  // Additional utility props
371
  id?: string | number | null;
372
}
373

374
// Mixin interfaces
375
interface MultiselectMixinProps {
376
  internalSearch?: boolean;
377
  options: any[];
378
  multiple?: boolean;
379
  trackBy?: string;
380
  label?: string;
381
  searchable?: boolean;
382
  clearOnSelect?: boolean;
383
  hideSelected?: boolean;
384
  placeholder?: string;
385
  allowEmpty?: boolean;
386
  resetAfter?: boolean;
387
  closeOnSelect?: boolean;
388
  customLabel?: (option: any, label: string) => string;
389
  taggable?: boolean;
390
  tagPlaceholder?: string;
391
  tagPosition?: string;
392
  max?: number | boolean;
393
  id?: string | number | null;
394
  optionsLimit?: number;
395
  groupValues?: string;
396
  groupLabel?: string;
397
  groupSelect?: boolean;
398
  blockKeys?: string[];
399
  preserveSearch?: boolean;
400
  preselectFirst?: boolean;
401
  preventAutofocus?: boolean;
402
  filteringSortFunc?: (a: any, b: any) => number;
403
}
404

405
interface PointerMixinProps {
406
  showPointer?: boolean;
407
  optionHeight?: number;
408
}
409

410
// Component definition with Vue 3 Composition API
411
interface MultiselectComponent extends DefineComponent<
412
  MultiselectProps,
413
  {},
414
  {},
415
  {},
416
  MultiselectMethods
417
> {}
418

419
// Main exports
420
export const Multiselect: MultiselectComponent;
421
export const multiselectMixin: DefineComponent<MultiselectMixinProps>;
422
export const pointerMixin: DefineComponent<PointerMixinProps>;
423
export default Multiselect;
424
```