ComboBox Component

A powerful combobox component that combines the features of a searchable dropdown with the ability to create custom entries. Users can either select from existing options or type their own values.

Overview

The ComboBox component provides:

• Single and multiple item selection with search
• Ability to create custom entries by typing
• Real-time filtering as you type
• Custom filter functions for advanced filtering
• Chip display for multiple selections
• Loading state support
• Customizable placement and positioning
• Keyboard navigation support
• Flexible item text and value mapping

When to Use

Use the ComboBox component when you need to:

• Create searchable select inputs where users can add custom values
• Implement tag input fields with predefined suggestions
• Build multi-select interfaces with custom entry capability
• Create flexible dropdown lists that accept freeform text
• Implement autocomplete with the ability to add new options

Key Features

• Selection Modes:

  • Single selection: Choose one item or create a custom value
  • Multiple selection: Select multiple items or create custom tags
  • Toggle selection: Deselect items by clicking again or removing chips

• Custom Entry Creation:

  • Type and press Enter to create custom entries
  • Single mode: Typed text becomes the value on blur or menu close
  • Multiple mode: Press Enter to create chips from typed text
  • Custom entries are stored and managed automatically

• Search & Filtering:

  • Real-time filtering as you type
  • Custom filter function support for advanced filtering
  • Smart scoring system (exact match, starts with, contains)
  • Selected items on top option when searching

• Display Features:

  • Chip display for multiple selections
  • Dynamic input placeholder based on selection state
  • Checkbox indicators for multiple mode
  • Loading spinner during data fetching
  • Clear button to reset selection

• Input Features:

  • Searchable input field
  • Clearable selection
  • Readonly and disabled states
  • Loading state with spinner
  • Custom placeholder text

• Interaction:

  • Click outside to close
  • ESC key to close
  • Enter key to create custom entries
  • Backspace to remove selected items (multiple mode)
  • Keyboard navigation support
  • Smooth animations and transitions

• Customization:

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

Props

Prop	Type	Default	Description
items	Array	[]	Array of items to display
modelValue	String/Number/Array/Object	null	Selected value(s)
itemText	String	'text'	Property name for item display text
itemValue	String	'value'	Property name for item value
itemDisabled	String	'disabled'	Property name for item disabled state
multiple	Boolean	false	Enable multiple selection
filterFunction	Function	null	Custom filter function
selectedOnTop	Boolean	false	Show selected items at the top
placement	String	'bottom'	Dropdown placement
offset	Array	[0, 0.125]	Offset from trigger
menuWidth	String/Number	null	Custom dropdown width
matchTriggerWidth	Boolean	true	Match dropdown width to trigger
placeholder	String	''	Input placeholder text
disabled	Boolean	false	Disable the combobox
loading	Boolean	false	Show loading state
clearable	Boolean	false	Show clear button
readonly	Boolean	false	Make input readonly

Events

Event	Payload	Description
update:modelValue	value	Emitted when selection changes
change	value	Emitted when selection changes
select	item, value	Emitted when item is selected
remove	item, value	Emitted when item is removed
search	searchText	Emitted when search text changes
create	item, value	Emitted when custom item is created

Slots

Slot	Props	Description
no-data	-	Custom no data content

Methods

Method	Description
focus()	Focus the input field
blur()	Blur the input field
openMenu()	Open the dropdown menu
closeMenu()	Close the dropdown menu
search(value)	Set the search text programmatically

Differences from Autocomplete

The ComboBox differs from the Autocomplete component in the following ways:

• Custom Entry Creation: Users can create new entries by typing and pressing Enter or closing the menu
• Freeform Input: Accepts any text input, not just predefined options
• Create Event: Emits a create event when new custom items are added
• Flexible Values: In single mode, the typed text becomes the value automatically

Demo →

API Reference →

View Code →