0
# Vue Select
1

2
Vue Select is a comprehensive Vue.js component that enhances the standard HTML select element with advanced functionality including filtering, searching, tagging, AJAX support, and accessibility features. It provides a lightweight (~20kb total), zero-dependency solution for creating sophisticated dropdown interfaces with support for single and multiple selections, custom styling through slots and SCSS variables, server-side rendering (SSR), and extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: vue-select
7
- **Package Type**: npm
8
- **Language**: JavaScript/Vue.js
9
- **Installation**: `npm install vue-select`
10

11
## Core Imports
12

13
```javascript
14
import vSelect from "vue-select";
15
```
16

17
Named imports:
18

19
```javascript
20
import { VueSelect, mixins } from "vue-select";
21
```
22

23
CSS import (required):
24

25
```javascript
26
import "vue-select/dist/vue-select.css";
27
```
28

29
For Vue 2 global registration:
30

31
```javascript
32
import Vue from "vue";
33
import vSelect from "vue-select";
34

35
Vue.component("v-select", vSelect);
36
```
37

38
## Basic Usage
39

40
```vue
41
<template>
42
  <div>
43
    <!-- Single selection -->
44
    <v-select 
45
      v-model="selected"
46
      :options="options"
47
      placeholder="Choose an option..."
48
    />
49
    
50
    <!-- Multiple selection -->
51
    <v-select
52
      v-model="multipleSelected"
53
      :options="options"
54
      multiple
55
      placeholder="Choose multiple options..."
56
    />
57
    
58
    <!-- Searchable with custom labels -->
59
    <v-select
60
      v-model="userSelected"
61
      :options="users"
62
      label="name"
63
      :reduce="user => user.id"
64
      placeholder="Search users..."
65
    />
66
  </div>
67
</template>
68

69
<script>
70
import vSelect from "vue-select";
71

72
export default {
73
  components: { vSelect },
74
  data() {
75
    return {
76
      selected: null,
77
      multipleSelected: [],
78
      userSelected: null,
79
      options: ["Option 1", "Option 2", "Option 3"],
80
      users: [
81
        { id: 1, name: "John Doe", email: "john@example.com" },
82
        { id: 2, name: "Jane Smith", email: "jane@example.com" }
83
      ]
84
    };
85
  }
86
};
87
</script>
88
```
89

90
## Architecture
91

92
Vue Select is built around several key architectural components:
93

94
- **Core Component**: Single Vue component (`Select.vue`) with extensive prop-based configuration
95
- **Mixin System**: Modular functionality through Vue mixins (ajax, typeAheadPointer, pointerScroll)
96
- **Slot System**: Comprehensive slot-based customization for all UI elements
97
- **Event System**: Rich event emission for lifecycle hooks and user interactions
98
- **Directive Support**: Custom directives for advanced positioning (appendToBody)
99
- **Accessibility Layer**: Full ARIA support with proper roles, labels, and keyboard navigation
100

101
## Capabilities
102

103
### Core Selection
104

105
Essential selection functionality supporting both single and multiple selection modes, with comprehensive value management and state tracking.
106

107
```javascript { .api }
108
// Main component props for selection
109
props: {
110
  value: Object | String | null,     // Currently selected value(s)
111
  multiple: Boolean,                 // Enable multiple selection
112
  options: Array,                    // Available options array
113
  disabled: Boolean,                 // Disable component
114
  clearable: Boolean,                // Show clear button
115
  inputId: String,                   // Input element id attribute
116
  resetOnOptionsChange: Boolean | Function // Control value reset behavior
117
}
118

119
// Core selection methods
120
methods: {
121
  select(option: Object | String): void,
122
  deselect(option: Object | String): void,
123
  clearSelection(): void
124
}
125

126
// Selection events
127
events: {
128
  'input': (value: any) => void,           // v-model value change
129
  'option:selected': (option: any) => void, // Option selected
130
  'option:deselected': (option: any) => void // Option deselected
131
}
132
```
133

134
[Core Selection](./selection.md)
135

136
### Search and Filtering
137

138
Built-in search functionality with customizable filtering logic, supporting real-time option filtering and custom match algorithms.
139

140
```javascript { .api }
141
// Search and filter props
142
props: {
143
  searchable: Boolean,              // Enable search input
144
  filterable: Boolean,             // Enable option filtering
145
  filterBy: Function,              // Custom filter matching logic
146
  filter: Function,               // Complete filter implementation
147
  clearSearchOnSelect: Boolean,   // Clear search on selection
148
  clearSearchOnBlur: Function    // Clear search on blur
149
}
150

151
// Search methods and computed properties
152
computed: {
153
  searching: Boolean,            // Current search state
154
  searchPlaceholder: String,     // Computed placeholder text
155
  filteredOptions: Array        // Options filtered by search
156
}
157

158
// Search events
159
events: {
160
  'search:focus': () => void,
161
  'search:blur': () => void,
162
  'search': (searchText: String, toggleLoading: Function) => void
163
}
164
```
165

166
[Search and Filtering](./search-filtering.md)
167

168
### Tagging and Creation
169

170
Dynamic option creation functionality allowing users to create new options from search input, with customizable creation logic and tag management.
171

172
```javascript { .api }
173
// Tagging props
174
props: {
175
  taggable: Boolean,           // Enable option creation
176
  pushTags: Boolean,          // Add created tags to options
177
  createOption: Function      // Custom option creation logic
178
}
179

180
// Tagging methods
181
methods: {
182
  pushTag(option: Object | String): void,
183
  optionExists(option: Object | String): Boolean
184
}
185

186
// Creation events
187
events: {
188
  'option:created': (option: Object | String) => void
189
}
190
```
191

192
[Tagging and Creation](./tagging.md)
193

194
### Keyboard Navigation
195

196
Complete keyboard navigation system with customizable key mappings, type-ahead functionality, and accessibility compliance.
197

198
```javascript { .api }
199
// Keyboard props
200
props: {
201
  selectOnKeyCodes: Array,        // Key codes for selection
202
  mapKeydown: Function,          // Custom keydown mapping
203
  tabindex: Number,              // Input tabindex
204
  autoscroll: Boolean            // Auto-scroll to highlighted option
205
}
206

207
// Navigation methods (from typeAheadPointer mixin)
208
methods: {
209
  typeAheadUp(): void,
210
  typeAheadDown(): void, 
211
  typeAheadSelect(): void,
212
  typeAheadToLastSelected(): void
213
}
214

215
// Navigation data
216
data: {
217
  typeAheadPointer: Number      // Current keyboard pointer position
218
}
219
```
220

221
[Keyboard Navigation](./keyboard-navigation.md)
222

223
### Customization and Styling
224

225
Extensive customization options through slots, component overrides, SCSS variables, and custom positioning for advanced use cases.
226

227
```javascript { .api }
228
// Customization props
229
props: {
230
  components: Object,           // Override child components
231
  placeholder: String,         // Placeholder text
232
  transition: String,          // Dropdown transition
233
  dir: String,                // Text direction (ltr/rtl/auto)
234
  appendToBody: Boolean,      // Append dropdown to body
235
  calculatePosition: Function  // Custom positioning logic
236
}
237

238
// Available slots
239
slots: {
240
  'header': Object,
241
  'selected-option-container': { option, deselect, multiple, disabled },
242
  'selected-option': Object,
243
  'search': Object,
244
  'open-indicator': Object,
245
  'spinner': Object,
246
  'list-header': Object,
247
  'option': Object,
248
  'no-options': Object,
249
  'list-footer': Object,
250
  'footer': Object
251
}
252
```
253

254
[Customization and Styling](./customization.md)
255

256
### AJAX and Loading States
257

258
Built-in support for asynchronous data loading with loading state management, search event handling, and server-side filtering integration.
259

260
```javascript { .api }
261
// AJAX props (from ajax mixin)
262
props: {
263
  loading: Boolean             // Show loading state
264
}
265

266
// Loading methods
267
methods: {
268
  toggleLoading(toggle?: Boolean): Boolean
269
}
270

271
// AJAX events
272
events: {
273
  'search': (searchText: String, toggleLoading: Function) => void
274
}
275

276
// Loading data
277
data: {
278
  mutableLoading: Boolean     // Internal loading state
279
}
280
```
281

282
[AJAX and Loading](./ajax-loading.md)
283

284
## Types
285

286
```javascript { .api }
287
// Core component interface
288
interface VueSelect extends Vue {
289
  // Props
290
  value?: Object | String | null;
291
  multiple?: Boolean;
292
  options?: Array;
293
  disabled?: Boolean;
294
  searchable?: Boolean;
295
  // ... (full prop list available in sub-docs)
296
  
297
  // Data
298
  search: String;
299
  open: Boolean;
300
  typeAheadPointer: Number;
301
  
302
  // Methods
303
  select(option: Object | String): void;
304
  deselect(option: Object | String): void;
305
  clearSelection(): void;
306
  toggleDropdown(event: Event): void;
307
  // ... (full method list available in sub-docs)
308
}
309

310
// Option value types
311
type OptionValue = String | Number | Object;
312

313
// Filter function signature
314
type FilterFunction = (options: Array, search: String) => Array;
315

316
// Reduce function signature  
317
type ReduceFunction = (option: Object) => any;
318

319
// Option creation function signature
320
type CreateOptionFunction = (option: String) => Object | String;
321
```