0
# Basic Selection
1

2
Core single and multiple selection functionality with v-model support, handling objects, arrays, strings, and numbers as option values.
3

4
## Capabilities
5

6
### Single Selection
7

8
Default selection mode where users can select one option at a time.
9

10
```typescript { .api }
11
/**
12
 * Single selection component props
13
 */
14
interface SingleSelectionProps {
15
  /** Current selected value, supports any type */
16
  modelValue?: any;
17
  /** Array of available options */
18
  options: any[];
19
  /** Property name for tracking object equality (default: 'id') */
20
  trackBy?: string;
21
  /** Property name for display labels in objects (default: 'label') */
22
  label?: string;
23
  /** Placeholder text when no option is selected */
24
  placeholder?: string;
25
  /** Disable the entire component */
26
  disabled?: boolean;
27
  /** Allow clearing the selection */
28
  allowEmpty?: boolean;
29
}
30
```
31

32
**Usage Example:**
33

34
```vue
35
<template>
36
  <VueMultiselect
37
    v-model="selectedUser"
38
    :options="users"
39
    track-by="id"
40
    label="name"
41
    placeholder="Select a user">
42
  </VueMultiselect>
43
</template>
44

45
<script>
46
export default {
47
  data() {
48
    return {
49
      selectedUser: null,
50
      users: [
51
        { id: 1, name: 'John Doe', email: 'john@example.com' },
52
        { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
53
      ]
54
    }
55
  }
56
}
57
</script>
58
```
59

60
### Multiple Selection
61

62
Allows selection of multiple options simultaneously, with v-model binding to an array.
63

64
```typescript { .api }
65
/**
66
 * Multiple selection component props
67
 */
68
interface MultipleSelectionProps {
69
  /** Array of currently selected values */
70
  modelValue?: any[];
71
  /** Array of available options */
72
  options: any[];
73
  /** Enable multiple selection mode */
74
  multiple: true;
75
  /** Property name for tracking object equality */
76
  trackBy?: string;
77
  /** Property name for display labels in objects */
78
  label?: string;
79
  /** Maximum number of selections allowed (0 = unlimited) */
80
  max?: number | boolean;
81
  /** Disable the entire component */
82
  disabled?: boolean;
83
}
84
```
85

86
**Usage Example:**
87

88
```vue
89
<template>
90
  <VueMultiselect
91
    v-model="selectedTags"
92
    :options="availableTags"
93
    :multiple="true"
94
    :max="5"
95
    track-by="id"
96
    label="name"
97
    placeholder="Select tags">
98
  </VueMultiselect>
99
</template>
100

101
<script>
102
export default {
103
  data() {
104
    return {
105
      selectedTags: [],
106
      availableTags: [
107
        { id: 1, name: 'Vue.js' },
108
        { id: 2, name: 'JavaScript' },
109
        { id: 3, name: 'TypeScript' }
110
      ]
111
    }
112
  }
113
}
114
</script>
115
```
116

117
### String and Number Options
118

119
Support for simple string and number arrays without object structures.
120

121
```typescript { .api }
122
/**
123
 * Simple value selection props
124
 */
125
interface SimpleValueProps {
126
  /** String, number, or array of strings/numbers */
127
  modelValue?: string | number | (string | number)[];
128
  /** Array of strings or numbers */
129
  options: (string | number)[];
130
  /** Enable multiple selection for arrays */
131
  multiple?: boolean;
132
  /** Placeholder text */
133
  placeholder?: string;
134
}
135
```
136

137
**Usage Example:**
138

139
```vue
140
<template>
141
  <VueMultiselect
142
    v-model="selectedColors"
143
    :options="colors"
144
    :multiple="true"
145
    placeholder="Choose colors">
146
  </VueMultiselect>
147
</template>
148

149
<script>
150
export default {
151
  data() {
152
    return {
153
      selectedColors: [],
154
      colors: ['Red', 'Green', 'Blue', 'Yellow', 'Purple']
155
    }
156
  }
157
}
158
</script>
159
```
160

161
### Value Comparison and Tracking
162

163
Controls how options are compared for equality and selection state.
164

165
```typescript { .api }
166
/**
167
 * Value tracking configuration
168
 */
169
interface ValueTrackingProps {
170
  /** 
171
   * Property name for comparing objects (default: 'id')
172
   * Used to determine if two objects represent the same option
173
   */
174
  trackBy?: string;
175
  
176
  /** 
177
   * Property name for display text (default: 'label')
178
   * Used to extract the display value from objects
179
   */
180
  label?: string;
181
  
182
  /**
183
   * Custom function to generate display labels
184
   * @param option - The option object
185
   * @param label - The label property name
186
   * @returns Custom formatted string
187
   */
188
  customLabel?: (option: any, label: string) => string;
189
}
190
```
191

192
**Usage Example:**
193

194
```vue
195
<template>
196
  <VueMultiselect
197
    v-model="selectedProduct"
198
    :options="products"
199
    track-by="sku"
200
    label="title"
201
    :custom-label="formatProductLabel">
202
  </VueMultiselect>
203
</template>
204

205
<script>
206
export default {
207
  data() {
208
    return {
209
      selectedProduct: null,
210
      products: [
211
        { sku: 'ABC123', title: 'Laptop', price: 999.99 },
212
        { sku: 'DEF456', title: 'Mouse', price: 29.99 }
213
      ]
214
    }
215
  },
216
  methods: {
217
    formatProductLabel({ title, price }) {
218
      return `${title} - $${price}`;
219
    }
220
  }
221
}
222
</script>
223
```
224

225
### Selection Events
226

227
Events emitted during selection operations.
228

229
```typescript { .api }
230
/**
231
 * Selection-related events
232
 */
233
interface SelectionEvents {
234
  /** Emitted when selection changes (v-model compatibility) */
235
  '@update:modelValue': (value: any) => void;
236
  
237
  /** Emitted when an option is selected */
238
  '@select': (selectedOption: any, id: string | number) => void;
239
  
240
  /** Emitted when an option is removed from selection */
241
  '@remove': (removedOption: any, id: string | number) => void;
242
  
243
  /** Emitted when dropdown opens */
244
  '@open': (id: string | number) => void;
245
  
246
  /** Emitted when dropdown closes */
247
  '@close': (value: any, id: string | number) => void;
248
}
249
```
250

251
### Selection State Management
252

253
Methods for programmatically controlling selection state.
254

255
```typescript { .api }
256
/**
257
 * Component methods for selection control
258
 */
259
interface SelectionMethods {
260
  /** Programmatically open the dropdown */
261
  activate(): void;
262
  
263
  /** Programmatically close the dropdown */
264
  deactivate(): void;
265
  
266
  /** Check if a specific option is currently selected */
267
  isSelected(option: any): boolean;
268
  
269
  /** Select or deselect an option programmatically */
270
  select(option: any, key?: string): void;
271
  
272
  /** Remove an option from current selection */
273
  removeElement(option: any, shouldClose?: boolean): void;
274
  
275
  /** Get the current selection in the correct format */
276
  getValue(): any;
277
}
278
```
279

280
## Form Integration
281

282
### HTML Form Support
283

284
Integration with HTML forms and validation.
285

286
```typescript { .api }
287
/**
288
 * Form integration props
289
 */
290
interface FormIntegrationProps {
291
  /** HTML name attribute for form submission */
292
  name?: string;
293
  
294
  /** HTML required attribute - validates when no selection */
295
  required?: boolean;
296
  
297
  /** HTML tabindex for keyboard navigation */
298
  tabindex?: number;
299
}
300
```
301

302
**Usage Example:**
303

304
```vue
305
<template>
306
  <form @submit="handleSubmit">
307
    <VueMultiselect
308
      v-model="selectedCategory"
309
      :options="categories"
310
      name="category"
311
      :required="true"
312
      :tabindex="1"
313
      placeholder="Select category">
314
    </VueMultiselect>
315
    
316
    <button type="submit">Submit</button>
317
  </form>
318
</template>
319
```
320

321
### Vuex Integration
322

323
Works seamlessly with Vuex store patterns.
324

325
```vue
326
<template>
327
  <VueMultiselect
328
    :model-value="selectedItems"
329
    @update:model-value="updateSelection"
330
    :options="availableItems">
331
  </VueMultiselect>
332
</template>
333

334
<script>
335
import { mapState, mapMutations } from 'vuex'
336

337
export default {
338
  computed: {
339
    ...mapState(['selectedItems', 'availableItems'])
340
  },
341
  methods: {
342
    ...mapMutations(['updateSelection'])
343
  }
344
}
345
</script>
346
```