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
```