Listbox
<cui-listbox>
Live Example
Selected: {{ selected || '(none)' }}
Documentation
cui-listbox
An accessible, keyboard-navigable listbox component for Vue 3 applications. Built on native <ul>/<li> semantics with full WAI-ARIA listbox/option role support, form integration via a hidden input, and built-in validation error display.
Features
- Accessible: Implements
role="listbox"/role="option"witharia-activedescendant,aria-selected,aria-labelledby, andaria-invalid - Keyboard Navigation: Arrow keys, Home, End, Enter, Space, and Escape
- Form Integration: Hidden
<input>carries the selected value for HTML form submission - Validation: Built-in error display slot and integration with
ComponentValErrorFns - Flexible Items: Supports plain arrays, arrays of objects, custom
valueField/textField - Disabled / Readonly: Full support via props and CSS
- Wraparound Navigation: Arrow keys wrap from last to first item and vice versa
- Custom Slot: Default slot allows fully custom
<li>markup instead of auto-generated items - Custom Item Content:
list-item-contentslot allows customizing the content of each auto-generated<li>while keeping its selection/click/keyboard behavior - Multiselect: Optional
multiselectmode with ctrl/cmd+click toggle and shift+click range selection, matching native listbox behavior. See Multiselect below.
Props
| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| id | String | null |
No | ID for the hidden input. Auto-generated if omitted |
| label | String | — | No | Visible label rendered above the listbox |
| modelValue | any | — | No | Currently selected value (v-model) |
| listItems | Array | — | No | Array of items to render. May be primitives or objects |
| valueField | String | — | No | Property name to use as the item value when items are objects |
| textField | String | — | No | Property name to use as the display text when items are objects |
| itemElementType | String | 'li' |
No | Element type used for keyboard navigation matching |
| required | Boolean | false |
No | Marks the field as required for validation |
| disabled | Boolean | false |
No | Disables the listbox and prevents selection |
| validateOn | Any | |||
| ull | No | Validation trigger. Assigning a new truthy value (different from the previous value) externally triggers validation, e.g. :validate-on="counter" and increment counter. |
||
| readonly | Boolean | false |
No | Prevents selection changes without disabling focus |
| multiselect | Boolean | false |
No | Enables selecting multiple options. See Multiselect below. |
| errorMsg | String | — | No | Validation error message displayed below the listbox |
Events
| Event | Payload | Description |
|---|---|---|
| update:model-value | any |
Emitted when a new item is selected (v-model) |
| change | Event | Emitted when the selected value changes from its original value |
| input | Event | Emitted on every value set |
| focus | Event | Emitted when the listbox or an option receives focus |
| blur | Event | Emitted when focus leaves the listbox entirely |
| error | string | Emitted when a validation error is set |
| clear-error | — | Emitted when a validation error is cleared |
Slots
Default slot
Replaces the auto-generated <li> items. Use this for fully custom item markup.
<cui-listbox v-model="selected" :listItems="null">
<li role="option" data-value="1" @click="selected = 1">Custom Item One</li>
<li role="option" data-value="2" @click="selected = 2">Custom Item Two</li>
</cui-listbox>
list-item-content slot
Customizes the content rendered inside each auto-generated <li> option, while keeping the component's default <li> wrapper markup (and its role, selection, click, and keyboard handling) intact. Use this instead of the default slot when you only need to change how each item's content looks — e.g., adding icons, badges, or secondary text — without having to reimplement selection/click behavior yourself.
Receives the following slot props:
| Slot Prop | Description |
|---|---|
| item | The raw item from listItems for this row |
| index | The zero-based index of the item within listItems |
| isSelected | true if this item is currently selected |
| text | The resolved display text for the item (via textField, if set) |
| value | The resolved value for the item (via valueField, if set) |
<cui-listbox
:listItems="countries"
value-field="code"
text-field="name"
v-model="selectedCountry"
label="Country">
<template #list-item-content="{ item, isSelected, text }">
<span class="flag" :class="`flag-${item.code.toLowerCase()}`"></span>
<span>{{ text }}</span>
<span v-if="isSelected" class="check-icon">✓</span>
</template>
</cui-listbox>
errors slot
Override the default error message display. Receives the following slot props:
| Slot Prop | Description |
|---|---|
| id | Component ID |
| value | Last emitted value |
| item | Last emitted item object |
| required | Required prop value |
| disabled | Disabled prop value |
| readonly | Readonly prop value |
| validateTrigger | Increments each time validation should be re-evaluated |
<cui-listbox v-model="selected" :listItems="items">
<template #errors="{ value, validateTrigger }">
<span v-if="!value && validateTrigger > 0" class="error">
Please select an item.
</span>
</template>
</cui-listbox>
Keyboard Navigation
Follows the WAI-ARIA Listbox Pattern:
| Key | Action |
|---|---|
| Arrow Down | Move focus to next option (wraps to first) |
| Arrow Up | Move focus to previous option (wraps to last) |
| Home | Move focus to first option |
| End | Move focus to last option |
| Enter | Select the focused option |
| Space | Select the focused option (single-select), or toggle its selection (multiselect) |
| Escape | Return focus to the listbox container |
In multiselect mode, mouse interactions also support:
| Interaction | Action |
|---|---|
| Click | Selects only the clicked option, replacing any prior selection |
| Ctrl/Cmd+Click | Toggles the clicked option in/out of the current selection |
| Shift+Click | Selects the contiguous range between the last-selected option and the clicked option |
Accessibility
| ARIA Attribute | Applied To | Value |
|---|---|---|
role="listbox" |
<ul> |
Identifies the container as a listbox widget |
role="option" |
<li> |
Identifies each item as a selectable option |
aria-activedescendant |
<ul> |
ID of the currently focused option |
aria-labelledby |
<ul> |
ID of the label <span> |
aria-invalid |
<ul> |
true when errorMsg is non-empty |
aria-selected |
<li> |
true for the currently selected option(s) |
aria-multiselectable |
<ul> |
Mirrors the multiselect prop |
NVDA / screen reader note: The
role="listbox"+role="option"combination causes NVDA to automatically enter application mode, passing arrow keys directly to the component'sonKeydownhandler rather than using NVDA's own virtual cursor.
Basic Usage
Plain array
<cui-listbox
:listItems="['Apple', 'Banana', 'Cherry']"
v-model="selectedFruit"
label="Choose a fruit" />
Array of objects
<cui-listbox
:listItems="countries"
value-field="code"
text-field="name"
v-model="selectedCountry"
label="Country" />
Disabled items
Individual options can be disabled by adding a disabled attribute or disabled class to <li> elements in the default slot:
<cui-listbox v-model="selected">
<li role="option" @click="selected = 1">Enabled</li>
<li role="option" disabled>Disabled</li>
<li role="option" class="disabled">Also Disabled</li>
</cui-listbox>
Multiselect
When multiselect is true, modelValue is expected to be an array of values instead of a single value.
<cui-listbox
:listItems="colors"
value-field="id"
text-field="name"
v-model="selectedColorIds"
:multiselect="true"
label="Colors" />
Selection behavior
Mouse interaction follows the native OS/listbox convention:
- Click an option to select only that option, replacing the current selection.
- Ctrl/Cmd+click an option to toggle it in or out of the current selection without affecting the rest.
- Shift+click an option to select the contiguous range of items between the last-selected option and the clicked option.
On the keyboard, Space toggles the focused option in/out of the current selection; Enter selects only the focused option (replacing the current selection), matching click behavior.
Toggling multiselect at runtime
If multiselect changes after the component has a value, modelValue is automatically converted to keep it consistent with the new mode:
- Single value → array (
multiselectbecomestrue): a non-null value is wrapped in a one-item array (valuebecomes[value]). Anull/undefinedvalue staysnull. - Array → single value (
multiselectbecomesfalse): an empty array becomesnull. A non-empty array keeps only its first element and discards the rest.
This conversion updates modelValue via the normal update:model-value emit, so a parent bound with v-model will see the converted value reflected back automatically.
Form submission
The component renders a hidden <input type="hidden"> whose value is the selected value JSON-serialized (JSON.stringify), so it supports primitives, whole objects, and arrays of either (the multiselect case) in a single form field. On the server (e.g., in a Razor Pages handler), deserialize the posted string with System.Text.Json to recover the original value or array of values.
Complete Example
<template>
<div>
<cui-listbox
id="roleList"
label="User Role"
:listItems="roles"
value-field="id"
text-field="name"
v-model="selectedRoleId"
:required="true"
:errorMsg="roleError"
@change="onRoleChange"
@blur="validateRole">
<template #errors="{ value, validateTrigger }">
<span v-if="!value && validateTrigger > 0" class="field-error">
A role is required.
</span>
</template>
</cui-listbox>
<p>Selected role ID: {{ selectedRoleId }}</p>
</div>
</template>
<script>
export default {
data() {
return {
selectedRoleId: null,
roleError: null,
roles: [
{ id: 1, name: 'Administrator' },
{ id: 2, name: 'Editor' },
{ id: 3, name: 'Viewer' },
]
};
},
methods: {
onRoleChange() {
this.roleError = null;
},
validateRole() {
this.roleError = this.selectedRoleId == null
? 'A role is required.'
: null;
}
}
};
</script>
Common Issues
Arrow keys not working with NVDA
Ensure items use role="option" (not role="listitem"). NVDA only enters application mode — which passes arrow keys to the component — when it detects a role="listbox" container with role="option" children.
Selected value not submitted with form
Ensure the name prop or the auto-generated Name is set. The component renders a hidden <input> that carries the selected value, JSON-serialized so it works for single values, objects, or arrays (multiselect).
modelValue isn't an array in multiselect mode
Make sure modelValue is initialized to an array (or null) before setting multiselect to true. If the component mounts with a non-array value while multiselect is already true, the initial value is coerced into a one-item array (or null) automatically, but subsequent updates from the parent should pass arrays.