Autocomplete

Autocomplete

The Autocomplete component provides a text input with dropdown suggestions as users type, helping them quickly find and select items from a list of options.

Basic Example

A simple autocomplete with string options

Search countries

<label class="label">Search countries</label>
<ae-autocomplete
placeholder="Start typing..."
data-options='["United States", "United Kingdom", "Canada", "Australia", "Germany", "France", "Japan", "China", "Brazil", "India"]'>
</ae-autocomplete>

Grouped Options

Autocomplete with grouped options

Search countries by region

<label class="label">Search countries by region</label>
<ae-autocomplete
placeholder="Start typing..."
data-options='[
  { "id": "us", "text": "United States", "group": "North America" },
  { "id": "ca", "text": "Canada", "group": "North America" },
  { "id": "mx", "text": "Mexico", "group": "North America" },
  { "id": "br", "text": "Brazil", "group": "South America" },
  { "id": "ar", "text": "Argentina", "group": "South America" },
  { "id": "pe", "text": "Peru", "group": "South America" },
  { "id": "gb", "text": "United Kingdom", "group": "Europe" },
  { "id": "de", "text": "Germany", "group": "Europe" },
  { "id": "fr", "text": "France", "group": "Europe" }
]'>
</ae-autocomplete>

Minimum Characters

Autocomplete with minimum 2 characters required

Type at least 2 characters

<label class="label">Type at least 2 characters</label>
<ae-autocomplete
placeholder="Type at least 2 characters..."
min-chars="2"
data-options='["Afghanistan", "Albania", "Algeria", "Andorra", "Angola", "Antigua and Barbuda", "Argentina", "Armenia", "Australia", "Austria"]'>
</ae-autocomplete>

Disabled State

Autocomplete in disabled state

Disabled autocomplete

<label class="label">Disabled autocomplete</label>
<ae-autocomplete
placeholder="This input is disabled"
value="Cannot edit this value"
disabled
data-options='["Option 1", "Option 2", "Option 3"]'>
</ae-autocomplete>

Basic Usage

<ae-autocomplete
  placeholder="Search countries"
  min-chars="2"
  max-items="5">
</ae-autocomplete>

// Setting options
const autocomplete = document.querySelector('ae-autocomplete');
autocomplete.options = [
  'Afghanistan', 'Albania', 'Algeria', 'Andorra', 'Angola',
  'Antigua and Barbuda', 'Argentina', 'Armenia', 'Australia', 'Austria'
];

// Or with more detailed option objects
autocomplete.options = [
  { id: 'af', text: 'Afghanistan', group: 'Asia' },
  { id: 'al', text: 'Albania', group: 'Europe' },
  { id: 'dz', text: 'Algeria', group: 'Africa' },
  // ...
];

// Listen for selection events
autocomplete.addEventListener('ae-autocomplete-select', (e) => {
  console.log('Selected:', e.detail.value, e.detail.option);
});

Properties

Property	Attribute	Type	Default	Description
options	—	Array	[]	Options to display in the dropdown
value	value	string	''	Current input value
placeholder	placeholder	string	'Start typing...'	Placeholder text for input
disabled	disabled	boolean	false	Whether the input is disabled
minChars	min-chars	number	1	Minimum characters before showing suggestions
maxItems	max-items	number	10	Maximum items to show
filterFn	—	function	—	Custom filter function

Events

Event	Detail	Description
ae-autocomplete-change	{ value: string, option: AutocompleteOption | null }	Fired when input value changes
ae-autocomplete-select	{ value: string, option: AutocompleteOption }	Fired when an option is selected

Methods

Method	Parameters	Description
setValue(value)	value: string	Sets the input value programmatically
clearValue()	—	Clears the current value
focus()	—	Focuses the input element

Slots

Name	Description
option	Custom template for option rendering
no-results	Content shown when no results match
clear	Custom template for the clear button
arrow	Custom template for the dropdown arrow

CSS Parts

Part	Description
input	The text input element
dropdown	The dropdown container
option	Each option in the dropdown
group-heading	Group heading for categorized options
clear	The clear button
arrow	The dropdown arrow

CSS Custom Properties

Property	Description
--ae-autocomplete-border-color	Border color for the input
--ae-autocomplete-background	Background color of the input
--ae-autocomplete-text-color	Text color of the input
--ae-autocomplete-border-radius	Corner radius for input and dropdown
--ae-autocomplete-highlight-background	Background for highlighted options
--ae-autocomplete-selected-background	Background for selected option
--ae-autocomplete-dropdown-shadow	Shadow for the dropdown
--ae-autocomplete-match-text-color	Text color for matching characters

Examples

Basic Autocomplete

<ae-autocomplete placeholder="Search countries"></ae-autocomplete>

<script>
  const autocomplete = document.querySelector('ae-autocomplete');
  autocomplete.options = [
    'United States', 'United Kingdom', 'Canada', 'Australia',
    'Germany', 'France', 'Japan', 'China', 'Brazil', 'India'
  ];
</script>

With Object Options and Groups

<ae-autocomplete placeholder="Search countries" min-chars="1"></ae-autocomplete>

<script>
  const autocomplete = document.querySelector('ae-autocomplete');
  autocomplete.options = [
    { id: 'us', text: 'United States', group: 'North America' },
    { id: 'ca', text: 'Canada', group: 'North America' },
    { id: 'mx', text: 'Mexico', group: 'North America' },
    { id: 'br', text: 'Brazil', group: 'South America' },
    { id: 'ar', text: 'Argentina', group: 'South America' },
    { id: 'gb', text: 'United Kingdom', group: 'Europe' },
    { id: 'de', text: 'Germany', group: 'Europe' },
    { id: 'fr', text: 'France', group: 'Europe' }
  ];
</script>

With Custom Filter

<ae-autocomplete placeholder="Search countries"></ae-autocomplete>

<script>
  const autocomplete = document.querySelector('ae-autocomplete');

  // Set options
  autocomplete.options = [
    'United States', 'United Kingdom', 'Canada', 'Australia'
  ];

  // Custom filter: match start of word
  autocomplete.filterFn = (query, option) => {
    const words = option.text.toLowerCase().split(' ');
    return words.some(word => word.startsWith(query.toLowerCase()));
  };
</script>

With Custom Option Template

<ae-autocomplete placeholder="Search users">
  <template slot="option">
    <div style="display: flex; align-items: center;">
      <img src="${option.data.avatar}" style="width: 24px; height: 24px; border-radius: 50%; margin-right: 8px;" />
      <div>
        <div style="font-weight: bold;">${option.text}</div>
        <div style="font-size: 0.8em; color: #666;">${option.data.email}</div>
      </div>
    </div>
  </template>
</ae-autocomplete>

<script>
  const autocomplete = document.querySelector('ae-autocomplete');

  // Set options with extra data
  autocomplete.options = [
    {
      id: '1',
      text: 'John Doe',
      data: {
        email: 'john@example.com',
        avatar: 'https://example.com/avatars/john.jpg'
      }
    },
    // More users...
  ];
</script>

Accessibility

The autocomplete component follows ARIA best practices:

• Uses role="combobox" for the input
• Uses role="listbox" for the dropdown
• Uses role="option" for individual options
• Supports keyboard navigation:
  • ArrowDown: Open dropdown or navigate to the next option
  • ArrowUp: Navigate to the previous option
  • Enter: Select highlighted option
  • Escape: Close dropdown
  • Tab: Close dropdown and move focus

Best Practices

• Provide clear placeholder text to indicate what users can search for
• Set an appropriate minChars value to balance usability and performance
• Consider grouping options for better organization when you have many items
• Provide feedback when no results match the query
• For complex data, consider using object options with additional data fields
• Add appropriate error handling if options are loaded asynchronously