Dropdown
<cui-dropdown>
Live Example
Selected: {{ country || '(none)' }}
Second example of dropdown inside a modal popup
Selected: {{ fruit || '(none)' }}
Documentation
A flexible dropdown/select component supporting grouped options, custom value/text fields, keyboard navigation, validation, accessibility, and integration with Vue's v-model.
Usage
<cui-dropdown
v-model="value"
label="Label Here"
:list-items="items"
value-field="id"
text-field="name"
:required="true"
placeholder="Select an option"
error-msg="Sample error"
/>
Props
| Name | Type | Default | Description |
|---|---|---|---|
| label | String | — | Label displayed above the dropdown. |
| listItems | Array | — | Array of items to display as options. |
| modelValue | Any | — | Value for v-model binding. |
| modelModifiers | Object | — | Vue v-model modifiers (e.g., lazy). |
| valueField | String | — | Property name on each item used as its value. If omitted, the item itself is used as the value. |
| textField | String | — | Property name on each item used as its display text. If omitted, the item itself is used as the text. |
| groupField | String | — | Property name on each item used to group options under a common header. |
| firstItem | Any | — | An item to always prepend to the top of the list (e.g., a placeholder/empty option). |
| placeholder | String | — | Placeholder text. |
| required | Boolean | false | Whether the field is required. |
| disabled | Boolean | false | Disables the dropdown. |
| validateOn | Any | null | 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 | Makes the dropdown read-only. |
| multiselect | Boolean | false | Enables selecting multiple options. See Multiselect below. |
| errorMsg | String | — | Error message to display. |
| bubbleErrors | Boolean | true | Controls if validation errors bubble to parent elements. |
Events
| Event Name | Payload | Description |
|---|---|---|
| update:model-value | value | Emitted when the selected value changes. |
| blur | event | Emitted on dropdown blur. |
| focus | event | Emitted on dropdown focus. |
| change | event | Emitted on value change. |
| input | event | Emitted on input. |
| click | event | Emitted when the dropdown is toggled open/closed. |
| error | {ctrlId, msgId, msg} | Emitted when an error occurs. |
| clear-error | {ctrlId, msgId, msg} | Emitted when an error is cleared. |
Slots
default: Custom content below the dropdown. Only rendered if provided by parent.
errors: Custom error display. Receives slot props:
id,value,item,required,disabled,readonly,validateTrigger.option-list: Custom rendering of the dropdown's option list, replacing the default list markup entirely. Receives slot props:
Prop Type Description items Array The parsed/grouped list of options to render (includes synthesized group header items when groupFieldis used).selectedValue Any The currently selected value, for comparison against each option. listItemValue Function (item) => value— resolves an option's value usingvalueField.listItemText Function (item) => text— resolves an option's display text usingtextField.isSelected Function (item) => boolean— whether the given option matchesselectedValue.selectOption Function (item) => void— selects the given option and closes the dropdown.isGroupItem Function (item) => boolean— whether the given option is a synthesized group header (not individually selectable).These are the same functions and data used internally to render the default option list, so you can use them to fully reproduce the default behavior or extend it (e.g., adding icons, descriptions, or custom grouping markup) while preserving selection, grouping, and accessibility semantics.
Example: customizing option rendering
<cui-dropdown v-model="value" :list-items="items" value-field="id" text-field="name"> <template v-slot:option-list="{ items, isSelected, isGroupItem, selectOption, listItemValue, listItemText }"> <div v-for="option in items" :key="listItemValue(option)" :role="isGroupItem(option) ? 'presentation' : 'option'" :class="{ selected: isSelected(option), 'option-group': isGroupItem(option) }" @click.stop="selectOption(option)"> <span v-if="!isGroupItem(option)" class="icon" :class="option.icon"></span> {{ listItemText(option) }} </div> </template> </cui-dropdown>
Multiselect
When multiselect is true, modelValue is expected to be an array of values instead of a single value. Clicking an option toggles its presence in the array rather than replacing the value and closing the dropdown, so users can select or deselect several options without the dropdown closing between selections.
<cui-dropdown
v-model="values"
label="Colors"
:list-items="colors"
value-field="id"
text-field="name"
:multiselect="true"
/>
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.
Native Validation
cui-dropdown supports native constraint validation through the required prop.
- When
requiredistrueand nothing is selected, the field is invalid: the browser'svalidationMessageis displayed in the errors area,aria-invalidis set, and anerrorevent is emitted (and bubbled whenbubbleErrorsistrue). - With
multiselect, an empty array is treated as no selection. - Selecting a value clears the error and emits
clear-error. - Validation runs on blur and when the
validate-onprop changes to a new truthy value. - The native constraint flags (such as
valueMissing) are available throughvalidityInfo.
<cui-dropdown v-model="value" label="Color" :list-items="items" value-field="id" text-field="name" :required="true" />
Overriding native messages with cui-valmsg
To show your own message instead of the browser's, place a cui-valmsg in the default slot with a priority higher than the native error's priority of 98. The dropdown shows only the highest priority error, so the custom message replaces the native one while the field is invalid.
<cui-dropdown v-model="value" label="Color" :list-items="items" value-field="id" text-field="name" :required="true" v-slot="ctrl">
<cui-valmsg :expr="$vFn.isRequired(ctrl?.value, ctrl?.required)"
msg="Please choose a color."
:priority="99"
:trigger-on="ctrl.validateTrigger" />
</cui-dropdown>
Notes:
cui-valmsgdefaults topriority1, which is lower than the native error, so set a priority above98(for example99) for the custom message to take precedence.- Use the
errorsslot instead if you need to replace how the error is rendered, rather than just its text.
Accessibility
- The dropdown control uses
role="combobox"and the options list usesrole="listbox"with individual options markedrole="option". - The options list sets
aria-multiselectableto match themultiselectprop. - Grouped items are rendered with
role="group"/role="presentation"and anaria-labelmatching the group heading. - Selected options are marked with
aria-selected. - Uses
aria-invalidon the input to indicate validation state. - Error messages are rendered in a container with
role="status". - Fully keyboard operable:
Enter/Spacetoggles or selects,Escapecloses the list,ArrowUp/ArrowDownnavigate options, and typing a character jumps to the next matching option.
Features
- Supports plain arrays of primitive values or arrays of objects via
valueField/textField. - Optional grouping of items via
groupField, rendering group headers with nested sub-items. - Optional
firstItemto prepend a default/placeholder option to the list. - Works with
v-modelandv-model.lazy. - Native and custom validation with error priority and event-based error handling, consistent with other cui components.
- Error events can bubble to parent elements via
bubbleErrors. - Conditionally renders slots only when used.
Validation
Native validation (e.g., required) is supported, along with custom validation events. To override the default error message, dispatch an error event with a higher priority than the native validation priority (98), e.g., 99. The error event payload should include ctrlId, msgId, msg, and priority.
The component listens for all error events dispatched by any child components (bubbled events) and will display the error message with the highest priority.