Combobox

The Combobox component combines a text input with a dropdown list, providing autocomplete functionality with keyboard navigation and accessibility features. It's ideal for selecting from a large list of options with search capability.

Examples

Basic Combobox

svelte

<Combobox 
  options={['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']}
  placeholder="Select a fruit"
  onchange={(e) => console.log(e.detail.value)}
/>

With Object Data

svelte

<Combobox 
  options={countries}
  optionLabel="name"
  optionValue="code"
  placeholder="Select a country"
  onchange={(e) => console.log(e.detail.value)}
/>

Custom Option Template

svelte

<Combobox 
  options={countries}
  optionLabel="name"
  optionValue="code"
  placeholder="Select a country"
  let:option
>
  <div class="flex items-center">
    <span class="mr-2 text-lg">{option.flag}</span>
    <span>{option.name}</span>
    <span class="ml-2 text-xs text-muted">({option.code})</span>
  </div>
</Combobox>

Disabled State

svelte

<Combobox 
  options={fruits}
  placeholder="Select a fruit"
  disabled
/>

Loading State

svelte

<Combobox 
  options={[]}
  placeholder="Loading options..."
  loading
/>

With Initial Value

svelte

<Combobox 
  options={fruits}
  placeholder="Select a fruit"
  value="Banana"
/>

Form Integration

Favorite Fruit

svelte

<div>
  <label for="fruit-select" class="block text-sm font-medium mb-1">Favorite Fruit</label>
  <Combobox 
    id="fruit-select"
    name="fruit"
    options={fruits}
    placeholder="Select a fruit"
    required
  />
</div>

Props

Prop	Type	Default	Description
`options`	`Array`	`[]`	Options to display in the dropdown
`value`	`any`	`null`	Current value
`placeholder`	`string`	`"Select an option"`	Placeholder text
`optionLabel`	`string`	`"label"`	Property name for option labels
`optionValue`	`string`	`"value"`	Property name for option values
`disabled`	`boolean`	`false`	Whether the combobox is disabled
`readonly`	`boolean`	`false`	Whether the combobox is readonly
`required`	`boolean`	`false`	Whether the combobox is required
`searchable`	`boolean`	`true`	Whether to allow searching
`clearable`	`boolean`	`true`	Whether to allow clearing the selection
`loading`	`boolean`	`false`	Whether to show a loading indicator
`autoSelect`	`boolean`	`false`	Whether to automatically select the first option
`openOnFocus`	`boolean`	`true`	Whether to open the dropdown on focus
`maxHeight`	`number`	`250`	Maximum height of the dropdown in pixels
`ariaLabel`	`string`	`undefined`	ARIA label for the combobox
`filter`	`Function`	`undefined`	Custom filter function
`name`	`string`	`undefined`	Name attribute for the input
`id`	`string`	`random UUID`	HTML id for accessibility
`class`	`string`	`""`	Additional CSS classes

Events

Event	Detail	Description
`change`	`{ value: any, option: any }`	Fired when the selection changes
`input`	`{ value: any, option: any }`	Fired when the input value changes

Slots

Slot	Props	Description
default	`{ option }`	Custom template for option items

Accessibility

The Combobox component follows WAI-ARIA guidelines for comboboxes:

Uses role="combobox" for the input element
Uses role="listbox" for the dropdown
Uses role="option" for each option
Proper aria-expanded, aria-controls, aria-activedescendant, and aria-selected attributes
Supports keyboard navigation
Provides proper focus management

Keyboard Support

Key	Function
`Tab`	Moves focus to the combobox
`Enter`	When dropdown is open, selects the highlighted option
`Escape`	Closes the dropdown
`ArrowDown`	Opens the dropdown if closed, or moves highlight to the next option
`ArrowUp`	Opens the dropdown if closed, or moves highlight to the previous option