0
# Keyboard Navigation
1
2
Complete keyboard navigation system with customizable key mappings, type-ahead functionality, and accessibility compliance.
3
4
## Capabilities
5
6
### Keyboard Configuration
7
8
Properties that control keyboard behavior and key mappings.
9
10
```javascript { .api }
11
/**
12
* Array of key codes that will select the current option
13
* Default is Enter key (13)
14
*/
15
selectOnKeyCodes: Array // default: [13]
16
17
/**
18
* Set the tabindex for the input field
19
*/
20
tabindex: Number // default: null
21
22
/**
23
* Used to modify the default keydown events map for the search input
24
* Allows customization of keyboard shortcuts
25
* @param map - Default keydown map
26
* @param vm - Vue Select instance
27
* @returns Modified keydown map
28
*/
29
mapKeydown: Function // default: (map, vm) => map
30
31
/**
32
* DEPRECATED: When true, hitting tab key will select current value
33
* Use selectOnKeyCodes instead
34
*/
35
selectOnTab: Boolean // default: false
36
37
/**
38
* DEPRECATED: Select current value if selectOnTab is enabled
39
* Use selectOnKeyCodes instead
40
*/
41
onTab: Function
42
43
/**
44
* Enable automatic scrolling to keep the highlighted option in view
45
* When navigating with keyboard, the dropdown will scroll automatically
46
*/
47
autoscroll: Boolean // default: true
48
```
49
50
### Type-Ahead Pointer System
51
52
Properties and methods for keyboard navigation within the dropdown options.
53
54
```javascript { .api }
55
// Data properties
56
data: {
57
/**
58
* Current position of keyboard navigation pointer in dropdown
59
* -1 means no option is highlighted
60
*/
61
typeAheadPointer: Number // default: -1
62
}
63
64
// Methods from typeAheadPointer mixin
65
methods: {
66
/**
67
* Move the typeAheadPointer visually up the list by
68
* setting it to the previous selectable option
69
*/
70
typeAheadUp(): void,
71
72
/**
73
* Move the typeAheadPointer visually down the list by
74
* setting it to the next selectable option
75
*/
76
typeAheadDown(): void,
77
78
/**
79
* Select the option at the current typeAheadPointer position
80
* Optionally clear the search input on selection
81
*/
82
typeAheadSelect(): void,
83
84
/**
85
* Move the pointer to the last selected option
86
* Useful for maintaining context in multiple selection
87
*/
88
typeAheadToLastSelected(): void
89
}
90
```
91
92
### Keyboard Event Handlers
93
94
Methods that handle various keyboard interactions.
95
96
```javascript { .api }
97
/**
98
* Search input keyboard event handler
99
* Handles navigation keys, selection keys, and special keys
100
* @param e - Keyboard event object
101
* @returns Keydown handler function
102
*/
103
onSearchKeyDown(e: KeyboardEvent): Function
104
105
/**
106
* Search input keypress handler
107
* @param e - Keyboard event object
108
*/
109
onSearchKeyPress(e: KeyboardEvent): void
110
111
/**
112
* Handle escape key press
113
* Removes search text or closes dropdown
114
*/
115
onEscape(): void
116
117
/**
118
* Delete value on Delete keypress when no text in search input
119
* Useful for removing selected options with keyboard
120
* @returns Deleted value or undefined
121
*/
122
maybeDeleteValue(): any
123
```
124
125
### Auto-Scrolling (from pointerScroll mixin)
126
127
Automatic scrolling functionality to keep the keyboard-highlighted option visible.
128
129
```javascript { .api }
130
/**
131
* Enable/disable auto-scrolling to keep pointer visible
132
*/
133
autoscroll: Boolean // default: true
134
135
/**
136
* Adjust the scroll position of the dropdown list
137
* if the current pointer is outside of the overflow bounds
138
* @returns Scroll adjustment result
139
*/
140
maybeAdjustScroll(): any
141
142
/**
143
* Get the currently viewable portion of the dropdown menu
144
* @returns Viewport bounds object
145
*/
146
getDropdownViewport(): Object
147
```
148
149
## Usage Examples
150
151
### Basic Keyboard Navigation
152
153
```vue
154
<template>
155
<v-select
156
v-model="selected"
157
:options="options"
158
placeholder="Use arrow keys to navigate, Enter to select..."
159
/>
160
</template>
161
162
<script>
163
export default {
164
data() {
165
return {
166
selected: null,
167
options: ['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5']
168
};
169
}
170
};
171
</script>
172
```
173
174
### Custom Key Mappings
175
176
```vue
177
<template>
178
<v-select
179
v-model="selected"
180
:options="options"
181
:selectOnKeyCodes="[13, 32]"
182
placeholder="Enter or Space to select..."
183
/>
184
</template>
185
186
<script>
187
export default {
188
data() {
189
return {
190
selected: null,
191
options: ['Option 1', 'Option 2', 'Option 3']
192
};
193
}
194
};
195
</script>
196
```
197
198
### Advanced Keydown Customization
199
200
```vue
201
<template>
202
<v-select
203
v-model="selected"
204
:options="filteredOptions"
205
:mapKeydown="customKeydown"
206
placeholder="Custom keyboard shortcuts enabled..."
207
/>
208
</template>
209
210
<script>
211
export default {
212
data() {
213
return {
214
selected: null,
215
options: ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']
216
};
217
},
218
computed: {
219
filteredOptions() {
220
return this.options;
221
}
222
},
223
methods: {
224
customKeydown(map, vm) {
225
return {
226
...map,
227
// Ctrl+A to select all (for multiple select)
228
'ctrl+65': (e) => {
229
e.preventDefault();
230
if (vm.multiple) {
231
vm.selectedValue = [...vm.options];
232
}
233
},
234
// Ctrl+D to clear selection
235
'ctrl+68': (e) => {
236
e.preventDefault();
237
vm.clearSelection();
238
},
239
// F1 for help
240
112: (e) => {
241
e.preventDefault();
242
alert('Keyboard shortcuts:\n' +
243
'Arrow keys: Navigate\n' +
244
'Enter/Space: Select\n' +
245
'Escape: Close\n' +
246
'Ctrl+A: Select all\n' +
247
'Ctrl+D: Clear selection');
248
}
249
};
250
}
251
}
252
};
253
</script>
254
```
255
256
### Tab Navigation with Custom Tabindex
257
258
```vue
259
<template>
260
<div>
261
<input tabindex="1" placeholder="First input" />
262
263
<v-select
264
v-model="selected"
265
:options="options"
266
:tabindex="2"
267
placeholder="Select with tabindex 2..."
268
/>
269
270
<input tabindex="3" placeholder="Third input" />
271
</div>
272
</template>
273
274
<script>
275
export default {
276
data() {
277
return {
278
selected: null,
279
options: ['Option 1', 'Option 2', 'Option 3']
280
};
281
}
282
};
283
</script>
284
```
285
286
### Multiple Selection with Keyboard Management
287
288
```vue
289
<template>
290
<v-select
291
v-model="selectedItems"
292
:options="options"
293
multiple
294
placeholder="Use Backspace to remove last item..."
295
@keydown.delete="handleDelete"
296
/>
297
</template>
298
299
<script>
300
export default {
301
data() {
302
return {
303
selectedItems: [],
304
options: [
305
'JavaScript', 'Python', 'Java', 'C++', 'Go',
306
'React', 'Vue.js', 'Angular', 'Node.js'
307
]
308
};
309
},
310
methods: {
311
handleDelete(event) {
312
// Custom delete handling
313
if (this.selectedItems.length > 0 && !this.$refs.vSelect.search) {
314
console.log('Removing last selected item via keyboard');
315
}
316
}
317
}
318
};
319
</script>
320
```
321
322
### Disabled Auto-Scroll
323
324
```vue
325
<template>
326
<v-select
327
v-model="selected"
328
:options="manyOptions"
329
:autoscroll="false"
330
placeholder="Navigate without auto-scrolling..."
331
/>
332
</template>
333
334
<script>
335
export default {
336
data() {
337
return {
338
selected: null,
339
manyOptions: Array.from({ length: 50 }, (_, i) => `Option ${i + 1}`)
340
};
341
}
342
};
343
</script>
344
```
345
346
### Keyboard Navigation Event Handling
347
348
```vue
349
<template>
350
<v-select
351
v-model="selected"
352
:options="options"
353
@search:focus="onFocus"
354
@search:blur="onBlur"
355
placeholder="Keyboard event monitoring..."
356
ref="vSelect"
357
/>
358
</template>
359
360
<script>
361
export default {
362
data() {
363
return {
364
selected: null,
365
options: ['Option 1', 'Option 2', 'Option 3']
366
};
367
},
368
methods: {
369
onFocus() {
370
console.log('Search input focused - keyboard navigation active');
371
},
372
onBlur() {
373
console.log('Search input blurred - keyboard navigation inactive');
374
}
375
},
376
mounted() {
377
// Monitor typeAheadPointer changes
378
this.$watch('$refs.vSelect.typeAheadPointer', (newPointer) => {
379
if (newPointer >= 0) {
380
const option = this.$refs.vSelect.filteredOptions[newPointer];
381
console.log('Keyboard pointer moved to:', option);
382
}
383
});
384
}
385
};
386
</script>
387
```
388
389
### Programmatic Keyboard Control
390
391
```vue
392
<template>
393
<div>
394
<v-select
395
v-model="selected"
396
:options="options"
397
ref="vSelect"
398
placeholder="Use buttons to control keyboard navigation..."
399
/>
400
401
<div class="controls">
402
<button @click="moveUp">β Up</button>
403
<button @click="moveDown">β Down</button>
404
<button @click="selectCurrent">β Select</button>
405
<button @click="focusSearch">π Focus</button>
406
</div>
407
</div>
408
</template>
409
410
<script>
411
export default {
412
data() {
413
return {
414
selected: null,
415
options: ['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5']
416
};
417
},
418
methods: {
419
moveUp() {
420
if (this.$refs.vSelect.open) {
421
this.$refs.vSelect.typeAheadUp();
422
}
423
},
424
moveDown() {
425
if (this.$refs.vSelect.open) {
426
this.$refs.vSelect.typeAheadDown();
427
}
428
},
429
selectCurrent() {
430
if (this.$refs.vSelect.open) {
431
this.$refs.vSelect.typeAheadSelect();
432
}
433
},
434
focusSearch() {
435
this.$refs.vSelect.searchEl.focus();
436
}
437
}
438
};
439
</script>
440
441
<style scoped>
442
.controls {
443
margin-top: 10px;
444
}
445
.controls button {
446
margin-right: 10px;
447
padding: 5px 10px;
448
}
449
</style>
450
```
451
452
### Accessibility-Enhanced Navigation
453
454
```vue
455
<template>
456
<v-select
457
v-model="selected"
458
:options="options"
459
:inputId="'accessible-select'"
460
aria-label="Choose your preferred programming language"
461
placeholder="Select programming language..."
462
/>
463
</template>
464
465
<script>
466
export default {
467
data() {
468
return {
469
selected: null,
470
options: [
471
'JavaScript', 'Python', 'Java', 'C#', 'Go',
472
'Rust', 'TypeScript', 'Kotlin', 'Swift'
473
]
474
};
475
}
476
};
477
</script>
478
```
479
480
## Default Key Mappings
481
482
Vue Select includes these default keyboard shortcuts:
483
484
- **Arrow Up/Down**: Navigate through options
485
- **Enter**: Select highlighted option
486
- **Escape**: Close dropdown or clear search
487
- **Tab**: Move to next focusable element (or select if selectOnTab enabled)
488
- **Backspace/Delete**: Remove last selected item (multiple mode) when search is empty
489
- **Page Up/Down**: Navigate quickly through long option lists
490
- **Home/End**: Jump to first/last option