Dropdown

A dropdown field for forms with popover-based options list.

Install

Run the following command to install the dropdown component:

npx acc-nuxt add Dropdown

Examples

Default

Searchable

Searchable with external search

With info

Please select your favorite fruit

Custom error

This is a custom error message

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.

Selected values: undefined

Selected values: undefined

Selected values: undefined

Sizes

Form

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

Basic Form

Form default values

Form disappearing

If the dropdown unmounts, 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.

Form values: { "fruit": null, "pref_fruit": null, "hidden_fruit": null, "fruitMax2": null } | Form errors: {}

Slots

#skeleton
Custom loading skeleton shown in the trigger when loading prop is true. Replaces the default LevSkeleton component.
#skeleton-option
Custom loading skeleton for options shown when loadingOptions or loadingMoreOptions is true. Replaces the default skeleton options.
#search="{ searchQuery: string, isInputFocused: boolean, setSearchQuery: (value: string) => void, setIsInputFocused: (value: boolean) => void }"
Custom search input component shown when searchable is enabled. Use the slot props to control the search state.
#no-options
Custom empty state shown when no options match the search query. Default shows "No results found" with a clear search button.
#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.

Emits

@load-more
Emitted when the user scrolls near the bottom of the options list. Used for implementing infinite scroll with external data loading.

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— 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.
direction:'top' | 'bottom'— optional
default:bottom
Direction the dropdown popover opens relative to the trigger.
searchable:boolean— optional
default:false
When true, shows a search input in the dropdown to filter options.
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.
popoverGap:number— optional
default:2
Gap between the trigger and the popover in px.
size:string— optional
default:md
Controls spacing. Options: xs, sm, md.

CSS Variables

--lev-dropdown-wrapper-width
default:100%
Width of the dropdown wrapper container.
--lev-dropdown-wrapper-display
default:flex
Display type of the wrapper.
--lev-dropdown-wrapper-flex-direction
default:column
Flex direction of the wrapper (stacks trigger, info, and error vertically).
--lev-dropdown-wrapper-gap
default:8px
Gap between wrapper children (trigger, info, error).
--lev-dropdown-popover-padding
default:4px
Padding inside the dropdown popover.
--lev-dropdown-trigger-padding
default:12px
Padding inside the trigger button.
--lev-dropdown-trigger-font-size
default:14px
Font size of the trigger text.
--lev-dropdown-trigger-line-height
default:18px
Line height of the trigger text.
--lev-dropdown-trigger-icon-size
default:16px
Icon size of the dropdown icon (⌄).
--lev-dropdown-trigger-border-radius
default:4px
Border radius of the trigger button.
--lev-dropdown-trigger-border
default:1px solid #c3c6c7
Border of the trigger button.
--lev-dropdown-trigger-bg
default:#ffffff
Background color of the trigger button.
--lev-dropdown-trigger-width
default:100%
Width of the trigger button.
--lev-dropdown-trigger-transition
default:border-color 100ms ease-out, background-color 100ms ease-out
Transition animation for trigger state changes.
--lev-dropdown-trigger-disabled-color
default:#858787
Text color when trigger is disabled.
--lev-dropdown-trigger-disabled-bg
default:#d4d7d9
Background color when trigger is disabled.
--lev-dropdown-trigger-hover-border-color
default:#aaacad
Border color on trigger hover.
--lev-dropdown-trigger-hover-bg
default:#f7f9fa
Background color on trigger hover.
--lev-dropdown-trigger-open-border-color
default:#1d66bf
Border color when dropdown is open.
--lev-dropdown-trigger-error-border-color
default:#ef4444
Border color when dropdown has an error.
--lev-dropdown-trigger-focus-outline
default:1px solid #1d66bf
Outline style when trigger is focused.
--lev-dropdown-trigger-focus-outline-offset
default:1px
Offset of the focus outline.
--lev-dropdown-trigger-right-icon-color
default:#141414
Color of the chevron icon in the trigger.
--lev-dropdown-placeholder-color
default:#141414
Color of the placeholder text when no value is selected.
--lev-dropdown-chips-gap
default:8px
Gap between chips in multiple selection mode.
--lev-dropdown-chip-padding
default:2px 4px 2px 6px
Padding inside each chip.
--lev-dropdown-chip-border-radius
default:4px
Border radius of chips (pill shape).
--lev-dropdown-chip-bg
default:#c3c6c7
Background color of chips.
--lev-dropdown-chip-color
default:#464747
Text color of chips.
--lev-dropdown-chip-border
default:none
Border of chips.
--lev-dropdown-chip-font-size
default:12px
Font size of the font inside the chips.
--lev-dropdown-chip-line-height
default:14px
Line height of the font inside the chips.
--lev-dropdown-chip-max-width
default:100%
Maximum width of chips.
--lev-dropdown-chip-text-max-width
default:160px
Maximum width of chip text before truncation.
--lev-dropdown-chip-remove-icon-size
default:12px
Size of the chip remove button (×), including padding.
--lev-dropdown-chip-remove-color
default:#464747
Color of the chip remove button.
--lev-dropdown-chip-remove-padding
default:0px
Padding of the chip remove button.
--lev-dropdown-chip-remove-margin-left
default:0px
Margin of the chip remove button on the left side.
--lev-dropdown-chip-remove-border-radius
default:4px
Border radius of the chip remove button.
--lev-dropdown-chip-remove-hover-color
default:#464747
Color of chip remove button on hover.
--lev-dropdown-chip-remove-hover-bg
default:#e1e4e5
Background of chip remove button on hover.
--lev-dropdown-options-gap
default:4px
Gap between options in the dropdown.
--lev-dropdown-options-max-height
default:288px
Maximum height of the options list before scrolling.
--lev-dropdown-option-padding-y
default:8px
Vertical padding of each option.
--lev-dropdown-option-padding-x
default:8px
Horizontal padding of each option.
--lev-dropdown-font-size
default:14px
Font size of option text.
--lev-dropdown-option-line-height
default:18px
Line height of option text.
--lev-dropdown-option-color
default:inherit
Text color of options.
--lev-dropdown-option-border-radius
default:4px
Border radius of option items.
--lev-dropdown-option-hover-bg
default:#f7f9fa
Background color of option on hover.
--lev-dropdown-option-active-bg
default:#e1e4e5
Background color of option when pressed.
--lev-dropdown-no-options-padding
default:8px 8px
Padding of the no options message container.
--lev-dropdown-no-options-color
default:#858787
Text color of the no options message.
--lev-dropdown-no-options-text-font-size
default:14px
Font size of the no options text and clear button.
--lev-dropdown-error-color
default:#ef4444
Color of the error message text.
--lev-dropdown-error-font-size
default:10px
Font size of the error message. Selector selects 'p' elements.
--lev-dropdown-info-font-size
default:10px
Font size of the info message. Selector selects 'p' elements.
--lev-dropdown-search-margin
default:4px 0
Margin around the search input when searchable is enabled.
--lev-dropdown-check-icon-size
default:16px
Size of the check icon container shown for selected options.

On This Page