AutoComplete

The AutoComplete component provides suggestions as you type, supporting both single and multiple selections. It's built on top of the base Input component and includes features like custom templates, keyboard navigation, and input masking.

Examples

Basic Usage

Country

<AutoComplete
  label="Country"
  items={countries}
  placeholder="Select a country"
/>

Multiple Selection

Countries

<AutoComplete
  label="Countries"
  items={countries}
  multiple={true}
  placeholder="Select countries"
/>

Custom Template

User

<AutoComplete
  label="User"
  items={users}
  itemTemplate={{
    render: ({ item }) => `
      <div class="flex items-center gap-2">
        <img src="${item.avatar}" alt="" class="w-8 h-8 rounded-full" />
        <span>${item.label}</span>
      </div>
    `
  }}
  placeholder="Select a user"
/>

Props

Prop	Type	Default	Description
`label`	`string`	Required	Input label
`items`	`Array<any>`	`[]`	Array of items to search through
`labelField`	`string`	`label`	Field to use for item labels
`valueField`	`string`	`value`	Field to use for item values
`value`	`string \| Array<string>`	Required	Selected value(s)
`minLength`	`number`	`1`	Minimum characters before showing suggestions
`delay`	`number`	`150`	Delay in ms before searching
`multiple`	`boolean`	`false`	Whether to allow multiple selections
`highlight`	`boolean`	`true`	Whether to highlight matching text
`forceSelection`	`boolean`	`false`	Whether to force selection from suggestions
`maxItems`	`number`	`10`	Maximum number of suggestions to show
`filter`	`function`	Required	Custom filter function (items, query) => filteredItems
`itemTemplate`	`Component`	Required	Custom item template component
`emptyMessage`	`string`	`No results found`	Message to show when no results are found
`loadingMessage`	`string`	`Loading...`	Message to show when loading
`loading`	`boolean`	`false`	Whether suggestions are loading
`disabled`	`boolean`	`false`	Whether the input is disabled

Events

Event	Detail Type	Description
`onselect`	`{ item: any } \| { items: Array<any> }`	Fired when an item is selected
`onremove`	`{ item: any }`	Fired when an item is removed (multiple mode)
`oninput`	`{ value: string }`	Fired when input value changes
`onfocus`	`void`	Fired when input gains focus
`onblur`	`void`	Fired when input loses focus

Keyboard Navigation

The AutoComplete component supports keyboard navigation:

ArrowDown - Highlight next suggestion
ArrowUp - Highlight previous suggestion
Enter - Select highlighted suggestion
Escape - Close suggestions

Accessibility

The component follows WAI-ARIA guidelines for combobox and listbox patterns:

Proper ARIA roles and attributes for the input and suggestions list
Keyboard navigation support
Screen reader announcements for loading and empty states
Proper focus management