Dropdown

A dropdown field that composes Popover for its options list.

Install

Run the following command to install the dropdown component:

npx acc-nuxt add Dropdown

Composition

Dropdown composes Popover for its options list.

Use popoverProps to configure the Popover. See the Popover documentation for its available props.

Examples

Default

Searchable

Searchable with external search

With info

Custom error

Loading

Disabled

Custom Option Slot

You can customize how options are rendered using the option slot.

Custom Value Slot

You can customize how the selected value is displayed in the trigger using the value slot.

Multiple Selection

Enable multiple selection by adding the multiple prop.

Multiple + Searchable

Combine multiple and searchable to let users filter options while selecting several values. Selected values are shown as removable chips.

Allow Create

Enable allowCreate (requires multiple + searchable) to let users add a new value that does not match any option by pressing Enter. The created value uses the typed query as both its label and value.

Allow Create without autocomplete

Set autocomplete to false so Enter always creates the typed value instead of selecting the first partial match. Exact matches are still selected as usual.

Sizes

Form

The dropdown component integrates with vee-validate for form handling.

Basic Form

Form default values

Form disappearing

If the dropdown unmounts, the value will be lost. But we can use keepValuesOnUnmount in the form setup to keep the value.

Form max 2 selections

Use zod schema to show error if more than 2 selections are made.

Props

options:AccDropdownOption[]
Array of options to display in the dropdown. Each option should have properties matching valueKey, labelKey, and optionally disabledKey.
multiple:boolean— optional
default:false
When true, allows selecting multiple options. Selected values are displayed as removable chips.
name:string— optional
Field name used for vee-validate form integration. Required when validate is true.
valueKey:string— optional
default:value
The key in each option object to use as the option value.
labelKey:string— optional
default:label
The key in each option object to use as the display label.
disabledKey:string— optional
default:disabled
The key in each option object to determine if the option is disabled.
placeholder:string— optional
Placeholder text shown when no value is selected.
validate:boolean— optional
default:true
When true, integrates with vee-validate for form validation. Requires name prop to be set.
defaultValue:string | number | null | (string | number)[]— optional
default:null
Initial value for the dropdown. For multiple selection, use an array.
disabled:boolean— optional
default:false
When true, disables the dropdown and prevents user interaction.
loading:boolean— optional
default:false
When true, shows a loading skeleton in the trigger and disables interaction.
info:string— optional
default:undefined
Info message displayed below the dropdown trigger.
customError:string— optional
default:undefined
Custom error message to display. Takes precedence over validation errors.
defaultError:string— optional
default:undefined
Initial error message to set via vee-validate setErrors.
disabledErrors:boolean— optional
default:false
When true, hides validation error messages. The customError prop is still shown, as it is managed manually.
searchable:boolean— optional
default:false
When true, shows a search input in the dropdown to filter options.
allowCreate:boolean— optional
default:false
When true in multiple mode, allows Enter to add a unique search value that does not exactly match an option.
autocomplete:boolean— optional
default:true
When allowCreate is enabled, controls whether Enter selects the first partial match or creates the typed value. Exact matches are always selected.
noOptionsLabel:string— optional
default:No results found
Text shown when the search has no matching options and no value can be created.
loadingOptions:boolean— optional
default:false
When true, shows skeleton loaders instead of options. Useful for async option loading.
loadingMoreOptions:boolean— optional
default:false
When true, shows skeleton loaders at the bottom of the options list. Used with infinite scroll.
popoverProps:AccPopoverProps— optional
default:{ direction: 'bottom', matchTriggerWidth: true }
Props forwarded to the Popover component used for the options list.
size:string— optional
default:md
Controls spacing. Options: xs, sm, md.

Bindings

v-model:string | number | null | undefined (single); (string | number)[] | null | undefined (multiple)
Selected option value or values. Single mode accepts and emits one string or number; multiple mode accepts and emits an array. Null and undefined represent no selection.
v-model:external-search-query:string | undefined
External search query used when searchable options are loaded remotely.

Emits

@update:modelValue
Emitted when the selected value changes. Emits one string or number in single mode, and an array in multiple mode.
@update:externalSearchQuery
Emitted when the external search query changes.
@load-more
Emitted when the user scrolls near the bottom of the options list. Used for implementing infinite scroll with external data loading.

Slots

#no-options
Custom empty state shown when no options match the search query. The default shows either the create prompt or the noOptionsLabel text.
#value="{ option: AccNormalizedOption | null, options: AccNormalizedOption[], removeOption: (value: string | number) => void }"
Custom display for the selected value in the trigger. For multiple selection, use options array and removeOption function.
#icon
Custom icon shown on the right side of the trigger. Default is a chevron that rotates when open.
#option="{ option: AccNormalizedOption }"
Custom display for each option in the dropdown list.
#checkIcon
Custom check icon shown next to selected options. Default is a checkmark icon.
#info
Custom info message content shown below the dropdown. Alternative to using the info prop.

CSS Variables

The dropdown wrapper can be customized using the following CSS variables.

--lev-dropdown-wrapper-width
default:100%
Controls the width of the dropdown wrapper.
--lev-dropdown-wrapper-display
default:flex
Controls the display mode of the dropdown wrapper.
--lev-dropdown-wrapper-flex-direction
default:column
Controls the flex direction of the dropdown wrapper.
--lev-dropdown-wrapper-gap
default:8px
Controls the gap between the dropdown and its messages.
--lev-dropdown-trigger-border
default:1px solid #c3c6c7
Controls the border of the dropdown trigger.
--lev-dropdown-trigger-border-radius
default:4px
Controls the border radius of the dropdown trigger.
--lev-dropdown-trigger-bg
default:#ffffff
Controls the background color of the dropdown trigger.
--lev-dropdown-trigger-font-size
default:14px
Controls the font size of the dropdown trigger.
--lev-dropdown-trigger-line-height
default:18px
Controls the line height of the dropdown trigger.
--lev-dropdown-trigger-gap
default:8px
Controls the gap between the value and the icon in the trigger.
--lev-dropdown-trigger-cursor
default:pointer
Controls the cursor of the dropdown trigger.
--lev-dropdown-trigger-transition
default:border-color 100ms ease-out, background-color 100ms ease-out
Controls the transition of the dropdown trigger.
--lev-dropdown-trigger-disabled-color
default:#858787
Controls the text color of the disabled dropdown trigger.
--lev-dropdown-trigger-disabled-bg
default:#e1e4e5
Controls the background color of the disabled dropdown trigger.
--lev-dropdown-trigger-disabled-cursor
default:not-allowed
Controls the cursor of the disabled dropdown trigger.
--lev-dropdown-trigger-hover-border-color
default:#aaacad
Controls the border color of the hovered dropdown trigger.
--lev-dropdown-trigger-hover-bg
default:#f7f9fa
Controls the background color of the hovered dropdown trigger.
--lev-dropdown-trigger-open-border-color
default:#1d66bf
Controls the border color of the open or focused-within dropdown trigger.
--lev-dropdown-trigger-error-border-color
default:#ef4444
Controls the border color of the dropdown trigger when it has an error.
--lev-dropdown-trigger-focus-outline
default:2px solid #1d66bf
Controls the focus-visible outline of the dropdown trigger.
--lev-dropdown-trigger-focus-outline-offset
default:-2px
Controls the focus-visible outline offset of the dropdown trigger.
--lev-dropdown-search-trigger-cursor
default:text
Controls the cursor of the searchable dropdown trigger.
--lev-dropdown-search-trigger-value-gap
default:4px
Controls the gap between chips and the search input in the searchable trigger.
--lev-dropdown-search-input-height
default:18px
Controls the height of the search input.
--lev-dropdown-search-autocomplete-color
default:#858787
Controls the text color of the autocomplete suggestion.
--lev-dropdown-search-autocomplete-line-height
default:18px
Controls the line height of the autocomplete suggestion.
--lev-dropdown-placeholder-color
default:#858787
Controls the color of the placeholder text.
--lev-dropdown-placeholder-disabled-color
default:#858787
Controls the color of the placeholder text when the trigger is disabled.
--lev-dropdown-search-placeholder-color
default:#858787
Controls the color of the search input placeholder.
--lev-dropdown-search-selected-placeholder-color
default:#141414
Controls the color of the search input placeholder when a value is selected.
--lev-dropdown-chips-gap
default:8px
Controls the gap between chips in multiple selection mode.
--lev-dropdown-chip-padding
default:2px 4px 2px 6px
Controls the padding of each chip.
--lev-dropdown-chip-border-radius
default:4px
Controls the border radius of each chip.
--lev-dropdown-chip-bg
default:#c3c6c7
Controls the background color of each chip.
--lev-dropdown-chip-color
default:#464747
Controls the text color of each chip.
--lev-dropdown-chip-font-size
default:12px
Controls the font size of each chip.
--lev-dropdown-chip-line-height
default:14px
Controls the line height of each chip.
--lev-dropdown-chip-pending-removal-outline
default:2px solid #1d66bf
Controls the outline of a chip pending removal (Backspace highlight).
--lev-dropdown-chip-pending-removal-outline-offset
default:-2px
Controls the outline offset of a chip pending removal.
--lev-dropdown-chip-text-max-width
default:160px
Controls the max width of the chip text before truncation.
--lev-dropdown-chip-remove-size
default:12px
Controls the size of the chip remove button.
--lev-dropdown-chip-remove-margin-left
default:4px
Controls the left margin of the chip remove button.
--lev-dropdown-chip-remove-color
default:#464747
Controls the color of the chip remove icon.
--lev-dropdown-chip-remove-cursor
default:pointer
Controls the cursor of the chip remove button.
--lev-dropdown-icon-size
default:16px
Controls the size of the trigger icon (chevron).
--lev-dropdown-option-check-size
default:16px
Controls the size of the check icon shown next to selected options.
--lev-dropdown-options-gap
default:4px
Controls the gap between options in the options list.
--lev-dropdown-options-max-height
default:288px
Controls the max height of the options list before scrolling.
--lev-dropdown-option-padding
default:8px
Controls the padding of each option.
--lev-dropdown-option-border-radius
default:4px
Controls the border radius of each option.
--lev-dropdown-option-font-size
default:14px
Controls the font size of each option.
--lev-dropdown-option-line-height
default:18px
Controls the line height of each option.
--lev-dropdown-option-cursor
default:pointer
Controls the cursor of each option.
--lev-dropdown-option-hover-bg
default:#f7f9fa
Controls the background color of a hovered or selected option.
--lev-dropdown-option-selected-bg
default:#f7f9fa
Controls the background color of a selected option.
--lev-dropdown-option-active-bg
default:#f7f9fa
Controls the background color of the active (keyboard-highlighted) option.
--lev-dropdown-option-focus-outline
default:2px solid #1d66bf
Controls the focus-visible outline of an option.
--lev-dropdown-option-focus-outline-offset
default:-2px
Controls the focus-visible outline offset of an option.
--lev-dropdown-option-disabled-cursor
default:not-allowed
Controls the cursor of a disabled option.
--lev-dropdown-option-disabled-opacity
default:0.5
Controls the opacity of a disabled option.
--lev-dropdown-no-options-padding
default:8px
Controls the padding of the no-options empty state.
--lev-dropdown-no-options-color
default:#858787
Controls the text color of the no-options empty state.
--lev-dropdown-no-options-font-size
default:14px
Controls the font size of the no-options empty state.
--lev-dropdown-loading-skeleton-option-height
default:34px
Controls the height of each loading option skeleton.
--lev-dropdown-loading-skeleton-border-radius
default:4px
Controls the border radius of loading skeletons.
--lev-popover-padding
default:4px
Controls the padding inside the Popover used for the dropdown options.

Wrapper Configuration

allowedSizes:readonly string[]
default:['xs', 'sm', 'md']
Sizes available to consumers through the copied wrapper.