Dropdown Component

A customizable dropdown/select component with support for single and multiple selection, custom triggers, and flexible item rendering.

Overview

The Dropdown component provides:

• Single and multiple item selection
• Customizable trigger elements
• Flexible item text and value mapping
• Chip display for multiple selections
• Custom placement and positioning
• Keyboard navigation support
• Customizable styling and behavior

When to Use

Use the Dropdown component when you need to:

• Create custom select inputs with enhanced styling
• Implement multi-select interfaces with chip display
• Build custom dropdown menus with specific triggers
• Create searchable or filterable dropdown lists
• Implement complex selection interfaces with custom item rendering

Key Features

• Selection Modes:

  • Single selection: Choose one item at a time
  • Multiple selection: Select multiple items with chip display
  • Toggle selection: Deselect items by clicking again

• Trigger Options:

  • Custom trigger slot for any element
  • Default button with dropdown icon
  • triggerContent slot to replace only the inner button content
  • Configurable trigger types (click, hover)
  • Disabled state support

• Item Management:

  • Flexible item structure with text/value mapping
  • Custom item rendering through slots
  • Selected items on top option
  • No data state handling

• Display Features:

  • Chip display for multiple selections
  • Dynamic button text based on selection
  • Checkbox indicators for multiple mode
  • Automatic trigger/menu width matching with optional overrides via buttonWidth and width

• Interaction:

  • Click outside to close
  • ESC key to close
  • Keyboard navigation support
  • Smooth animations and transitions

• Customization:

  • Custom placement (top, bottom, left, right)
  • Offset configuration
  • Custom width settings
  • Flexible styling options

Props

Prop	Type	Default	Description
items	Array	[]	Array of items to display
modelValue	Array/String/Number/Object	[]	Selected value(s)
itemText	String	'text'	Property name for item display text
itemValue	String	'value'	Property name for item value
multiple	Boolean	false	Enable multiple selection
disabled	Boolean	false	Disable the dropdown
buttonText	String	'Select'	Default button text
noDataText	String	'No items available'	Text when no items available
selectedOnTop	Boolean	false	Show selected items at the top
triggerType	String	'click'	Trigger type (click, hover)
placement	String	'bottom-start'	Dropdown placement
offset	Array	[0, 0.125]	Offset from trigger
closeOnOutsideClick	Boolean	true	Close on outside click
closeOnEsc	Boolean	true	Close on ESC key
buttonWidth	String/Number	'auto'	Width applied to the trigger button
width	String/Number	null	Custom dropdown width

Events

Event	Payload	Description
update:modelValue	value	Emitted when selection changes
item:select	item	Emitted when item is selected
item:unselect	item	Emitted when item is unselected
menu:open	-	Emitted when menu opens
menu:close	-	Emitted when menu closes

Slots

Slot	Props	Description
trigger	{ isOpen, selectedItems, toggleMenu, openMenu, closeMenu }	Custom trigger element
triggerContent	{ props }	Replace the contents of the default trigger button
item	{ item, selected, toggle }	Custom item rendering
no-data	-	Custom no data content

Methods

Method	Description
openMenu()	Open the dropdown menu
closeMenu()	Close the dropdown menu
toggleMenu()	Toggle the dropdown menu

API Reference →

View Code →