0
# Advanced Configuration
1

2
Extensive configuration options for behavior control, limits, keyboard handling, and UI customization.
3

4
## Capabilities
5

6
### Selection Limits
7

8
Control the maximum number of selections and display limits.
9

10
```typescript { .api }
11
/**
12
 * Selection limit configuration props
13
 */
14
interface SelectionLimitProps {
15
  /** Maximum number of selections allowed (0 = unlimited, default: false) */
16
  max?: number | boolean;
17
  
18
  /** Maximum number of selected options to display (default: 99999) */
19
  limit?: number;
20
  
21
  /** 
22
   * Function to generate text for excess selections
23
   * @param count - Number of selections beyond the limit
24
   * @returns Formatted string for display
25
   */
26
  limitText?: (count: number) => string;
27
}
28
```
29

30
**Usage Example:**
31

32
```vue
33
<template>
34
  <VueMultiselect
35
    v-model="selectedTags"
36
    :options="availableTags"
37
    :multiple="true"
38
    :max="5"
39
    :limit="3"
40
    :limit-text="formatLimitText"
41
    placeholder="Select up to 5 tags">
42
  </VueMultiselect>
43
</template>
44

45
<script>
46
export default {
47
  data() {
48
    return {
49
      selectedTags: [],
50
      availableTags: ['JavaScript', 'Vue.js', 'React', 'Angular', 'TypeScript', 'Node.js']
51
    }
52
  },
53
  methods: {
54
    formatLimitText(count) {
55
      return `and ${count} more tag${count === 1 ? '' : 's'}`;
56
    }
57
  }
58
}
59
</script>
60
```
61

62
### Behavior Control
63

64
Configure component behavior for various user interactions.
65

66
```typescript { .api }
67
/**
68
 * Behavior control configuration props
69
 */
70
interface BehaviorControlProps {
71
  /** Close dropdown after selecting an option (default: true) */
72
  closeOnSelect?: boolean;
73
  
74
  /** Clear search input after selecting an option (default: true) */
75
  clearOnSelect?: boolean;
76
  
77
  /** Hide already selected options from dropdown (default: false) */
78
  hideSelected?: boolean;
79
  
80
  /** Allow clearing all selections (default: true) */
81
  allowEmpty?: boolean;
82
  
83
  /** Reset component state after selection (stateless mode, default: false) */
84
  resetAfter?: boolean;
85
  
86
  /** Auto-select first option when no value is set (default: false) */
87
  preselectFirst?: boolean;
88
}
89
```
90

91
**Usage Example:**
92

93
```vue
94
<template>
95
  <VueMultiselect
96
    v-model="selectedSkills"
97
    :options="skills"
98
    :multiple="true"
99
    :close-on-select="false"
100
    :clear-on-select="false"
101
    :hide-selected="true"
102
    :allow-empty="true"
103
    placeholder="Add your skills">
104
  </VueMultiselect>
105
</template>
106

107
<script>
108
export default {
109
  data() {
110
    return {
111
      selectedSkills: [],
112
      skills: ['JavaScript', 'Python', 'Java', 'C++', 'Go', 'Rust']
113
    }
114
  }
115
}
116
</script>
117
```
118

119
### Loading States
120

121
Display loading indicators during async operations.
122

123
```typescript { .api }
124
/**
125
 * Loading state configuration props
126
 */
127
interface LoadingStateProps {
128
  /** Show loading spinner (default: false) */
129
  loading?: boolean;
130
  
131
  /** Disable component during loading */
132
  disabled?: boolean;
133
}
134
```
135

136
**Usage Example:**
137

138
```vue
139
<template>
140
  <VueMultiselect
141
    v-model="selectedUser"
142
    :options="users"
143
    :loading="isLoading"
144
    :disabled="isLoading"
145
    @search-change="searchUsers"
146
    :internal-search="false"
147
    placeholder="Search users...">
148
    
149
    <template #loading>
150
      <div class="custom-loading">
151
        <span>Searching users...</span>
152
      </div>
153
    </template>
154
  </VueMultiselect>
155
</template>
156

157
<script>
158
export default {
159
  data() {
160
    return {
161
      selectedUser: null,
162
      users: [],
163
      isLoading: false
164
    }
165
  },
166
  methods: {
167
    async searchUsers(query) {
168
      if (!query) return;
169
      
170
      this.isLoading = true;
171
      try {
172
        const response = await fetch(`/api/users/search?q=${query}`);
173
        this.users = await response.json();
174
      } finally {
175
        this.isLoading = false;
176
      }
177
    }
178
  }
179
}
180
</script>
181
```
182

183
### Keyboard Navigation
184

185
Configure keyboard behavior and shortcuts.
186

187
```typescript { .api }
188
/**
189
 * Keyboard navigation configuration props
190
 */
191
interface KeyboardNavigationProps {
192
  /** Array of keyboard keys to block during selection */
193
  blockKeys?: string[];
194
  
195
  /** Prevent automatic focus when component activates (default: false) */
196
  preventAutofocus?: boolean;
197
  
198
  /** HTML tabindex for keyboard navigation order */
199
  tabindex?: number;
200
}
201
```
202

203
**Usage Example:**
204

205
```vue
206
<template>
207
  <VueMultiselect
208
    v-model="selectedOption"
209
    :options="options"
210
    :block-keys="['Delete', 'Backspace']"
211
    :prevent-autofocus="true"
212
    :tabindex="2"
213
    placeholder="Keyboard navigation disabled">
214
  </VueMultiselect>
215
</template>
216

217
<script>
218
export default {
219
  data() {
220
    return {
221
      selectedOption: null,
222
      options: ['Option 1', 'Option 2', 'Option 3']
223
    }
224
  }
225
}
226
</script>
227
```
228

229
### Display Customization
230

231
Customize the visual presentation and layout.
232

233
```typescript { .api }
234
/**
235
 * Display customization configuration props
236
 */
237
interface DisplayCustomizationProps {
238
  /** Maximum height of dropdown in pixels (default: 300) */
239
  maxHeight?: number;
240
  
241
  /** Force dropdown opening direction ('above' | 'below' | '', default: '') */
242
  openDirection?: string;
243
  
244
  /** Show labels for keyboard interactions (default: true) */
245
  showLabels?: boolean;
246
  
247
  /** Show "No options" message when options array is empty (default: true) */
248
  showNoOptions?: boolean;
249
  
250
  /** Show "No results" message when search yields no results (default: true) */
251
  showNoResults?: boolean;
252
  
253
  /** Use Vue 3 Teleport for dropdown positioning (default: false) */
254
  useTeleport?: boolean;
255
}
256
```
257

258
**Usage Example:**
259

260
```vue
261
<template>
262
  <VueMultiselect
263
    v-model="selectedItem"
264
    :options="largeOptionsList"
265
    :max-height="200"
266
    open-direction="above"
267
    :show-labels="false"
268
    :use-teleport="true"
269
    placeholder="Customized dropdown">
270
    
271
    <template #noOptions>
272
      <div class="custom-no-options">
273
        <i class="icon-search"></i>
274
        <p>No items available</p>
275
      </div>
276
    </template>
277
    
278
    <template #noResult="{ search }">
279
      <div class="custom-no-results">
280
        <p>No results found for "{{ search }}"</p>
281
        <button @click="clearSearch">Clear search</button>
282
      </div>
283
    </template>
284
  </VueMultiselect>
285
</template>
286

287
<script>
288
export default {
289
  data() {
290
    return {
291
      selectedItem: null,
292
      largeOptionsList: Array.from({ length: 1000 }, (_, i) => `Item ${i + 1}`)
293
    }
294
  },
295
  methods: {
296
    clearSearch() {
297
      // Clear search functionality
298
      this.$refs.multiselect.updateSearch('');
299
    }
300
  }
301
}
302
</script>
303
```
304

305
### Performance Optimization
306

307
Configure options for optimal performance with large datasets.
308

309
```typescript { .api }
310
/**
311
 * Performance optimization configuration props
312
 */
313
interface PerformanceOptimizationProps {
314
  /** Maximum number of options to display in dropdown (default: 1000) */
315
  optionsLimit?: number;
316
  
317
  /** Disable internal search for async/custom filtering (default: true) */
318
  internalSearch?: boolean;
319
  
320
  /** Custom sorting function for search results */
321
  filteringSortFunc?: (a: any, b: any) => number;
322
}
323
```
324

325
**Usage Example:**
326

327
```vue
328
<template>
329
  <VueMultiselect
330
    v-model="selectedCity"
331
    :options="filteredCities"
332
    :options-limit="50"
333
    :internal-search="false"
334
    :filtering-sort-func="sortByPopulation"
335
    @search-change="debounceSearch"
336
    placeholder="Search cities...">
337
  </VueMultiselect>
338
</template>
339

340
<script>
341
export default {
342
  data() {
343
    return {
344
      selectedCity: null,
345
      allCities: [], // Large dataset of cities
346
      filteredCities: [],
347
      searchTimeout: null
348
    }
349
  },
350
  methods: {
351
    debounceSearch(query) {
352
      clearTimeout(this.searchTimeout);
353
      this.searchTimeout = setTimeout(() => {
354
        this.performSearch(query);
355
      }, 300);
356
    },
357
    
358
    performSearch(query) {
359
      if (!query) {
360
        this.filteredCities = this.allCities.slice(0, 50);
361
        return;
362
      }
363
      
364
      this.filteredCities = this.allCities
365
        .filter(city => city.name.toLowerCase().includes(query.toLowerCase()))
366
        .slice(0, 50);
367
    },
368
    
369
    sortByPopulation(a, b) {
370
      return b.population - a.population;
371
    }
372
  }
373
}
374
</script>
375
```
376

377
### Navigation and Pointer
378

379
Control dropdown navigation highlighting and option height calculations.
380

381
```typescript { .api }
382
/**
383
 * Navigation and pointer configuration props
384
 */
385
interface NavigationPointerProps {
386
  /** Enable/disable highlighting of the pointed value (default: true) */
387
  showPointer?: boolean;
388
  
389
  /** Height of each option in pixels for scroll calculations (default: 40) */
390
  optionHeight?: number;
391
}
392
```
393

394
**Usage Example:**
395

396
```vue
397
<template>
398
  <VueMultiselect
399
    v-model="selectedOption"
400
    :options="longOptionsList"
401
    :show-pointer="true"
402
    :option-height="35"
403
    placeholder="Navigate with arrow keys">
404
  </VueMultiselect>
405
</template>
406

407
<script>
408
export default {
409
  data() {
410
    return {
411
      selectedOption: null,
412
      longOptionsList: Array.from({ length: 1000 }, (_, i) => `Option ${i + 1}`)
413
    }
414
  }
415
}
416
</script>
417
```
418

419
### Component State Reset
420

421
Configure automatic state reset for stateless usage patterns.
422

423
```typescript { .api }
424
/**
425
 * State reset configuration props
426
 */
427
interface StateResetProps {
428
  /** Reset internal state after each selection (default: false) */
429
  resetAfter?: boolean;
430
  
431
  /** Preserve search value across selections (default: false) */
432
  preserveSearch?: boolean;
433
}
434
```
435

436
**Usage Example:**
437

438
```vue
439
<template>
440
  <VueMultiselect
441
    v-model="currentSelection"
442
    :options="dynamicOptions"
443
    :reset-after="true"
444
    :preserve-search="false"
445
    @select="handleSelection"
446
    placeholder="Stateless selector">
447
  </VueMultiselect>
448
</template>
449

450
<script>
451
export default {
452
  data() {
453
    return {
454
      currentSelection: null,
455
      dynamicOptions: [],
456
      selectionHistory: []
457
    }
458
  },
459
  methods: {
460
    handleSelection(selected) {
461
      // Process selection
462
      this.selectionHistory.push(selected);
463
      
464
      // Update options based on selection
465
      this.updateOptionsForNextSelection(selected);
466
    },
467
    
468
    updateOptionsForNextSelection(lastSelected) {
469
      // Logic to update options based on previous selection
470
      this.dynamicOptions = this.getNextOptions(lastSelected);
471
    }
472
  }
473
}
474
</script>
475
```
476

477
### Accessibility Configuration
478

479
Configure accessibility features and ARIA attributes.
480

481
```typescript { .api }
482
/**
483
 * Accessibility configuration props
484
 */
485
interface AccessibilityProps {
486
  /** HTML required attribute when no value selected */
487
  required?: boolean;
488
  
489
  /** Tab index for keyboard navigation */
490
  tabindex?: number;
491
  
492
  /** Component name for form submission and ARIA labels */
493
  name?: string;
494
  
495
  /** Enable spellcheck on search input */
496
  spellcheck?: boolean;
497
  
498
  /** Show pointer/selection labels for screen readers */
499
  showLabels?: boolean;
500
}
501
```
502

503
**Usage Example:**
504

505
```vue
506
<template>
507
  <VueMultiselect
508
    v-model="selectedAccessibleOption"
509
    :options="accessibleOptions"
510
    :required="true"
511
    :tabindex="1"
512
    name="accessible-select"
513
    :spellcheck="true"
514
    :show-labels="true"
515
    select-label="Press enter to select this option"
516
    deselect-label="Press enter to remove this option"
517
    placeholder="Accessible multiselect">
518
  </VueMultiselect>
519
</template>
520
```
521

522
### Advanced Event Handling
523

524
Configure component identification for complex event handling scenarios.
525

526
```typescript { .api }
527
/**
528
 * Event handling configuration props
529
 */
530
interface EventHandlingProps {
531
  /** 
532
   * Unique identifier passed with all events for component identification
533
   * Useful when multiple multiselect components exist
534
   */
535
  id?: string | number | null;
536
}
537

538
/**
539
 * All events include the component ID as second parameter
540
 */
541
interface EventHandlingEvents {
542
  '@update:modelValue': (value: any, id: string | number) => void;
543
  '@select': (option: any, id: string | number) => void;
544
  '@remove': (option: any, id: string | number) => void;
545
  '@search-change': (query: string, id: string | number) => void;
546
  '@open': (id: string | number) => void;
547
  '@close': (value: any, id: string | number) => void;
548
  '@tag': (query: string, id: string | number) => void;
549
}
550
```
551

552
**Usage Example:**
553

554
```vue
555
<template>
556
  <div>
557
    <VueMultiselect
558
      v-model="userSelection"
559
      :options="users"
560
      id="user-selector"
561
      @select="handleSelect"
562
      @remove="handleRemove">
563
    </VueMultiselect>
564
    
565
    <VueMultiselect
566
      v-model="roleSelection"
567
      :options="roles"
568
      id="role-selector"
569
      @select="handleSelect"
570
      @remove="handleRemove">
571
    </VueMultiselect>
572
  </div>
573
</template>
574

575
<script>
576
export default {
577
  methods: {
578
    handleSelect(option, componentId) {
579
      console.log(`Selected ${option.name} from ${componentId}`);
580
      
581
      if (componentId === 'user-selector') {
582
        this.handleUserSelection(option);
583
      } else if (componentId === 'role-selector') {
584
        this.handleRoleSelection(option);
585
      }
586
    },
587
    
588
    handleRemove(option, componentId) {
589
      console.log(`Removed ${option.name} from ${componentId}`);
590
    }
591
  }
592
}
593
</script>
594
```