Autocomplete

Add autocomplete to a text input inside .field. AutoInit() starts every .autocomplete except those with no-autoinit. The default data list is empty, so pass options, or call init, to give it something to suggest.

Set isMultiSelect: true to pick several values. A count appears on the field.

Set disabled: true on an entry to show it without letting anyone choose it. Oslo is unavailable, and Vienna is selected and cannot be removed.

Set group on entries to list them under headings.

<div class="field">
  <span class="material-symbols prefix" aria-hidden="true">textsms</span>
  <input type="text" id="autocomplete-input" class="autocomplete" placeholder=" ">
  <label for="autocomplete-input">Autocomplete</label>
</div>

Initialization

The IIFE bundle exposes Expressive.Autocomplete. data is an array of objects:

• id (required). A string or number, used as the option text when text is omitted.
• text. The display label. The default search matches id and text.
• image. An image URL, shown as a circle. The default search ignores it.
• description. An optional secondary line under the label.
• disabled. true keeps the entry in the list, dimmed, but nobody can choose it.
• group. An optional heading to list the entry under.

The default search ignores extra properties. Filter them yourself in onSearch.

document.addEventListener('DOMContentLoaded', function() {
  const elems = document.querySelectorAll('.autocomplete');
  Expressive.Autocomplete.init(elems, {
    minLength: 0,
    data: [
      { id: 12, text: 'Apple' },
      { id: 13, text: 'Microsoft' },
      { id: 42, text: 'Google', image: 'https://picsum.photos/id/64/250/250' }
    ]
  });
});

Multiple selection:

Expressive.Autocomplete.init(document.querySelector('#autocomplete-multi'), {
  minLength: 0,
  isMultiSelect: true,
  data: [
    { id: 12, text: 'Apple' },
    { id: 13, text: 'Microsoft' },
    { id: 42, text: 'Google', image: 'https://picsum.photos/id/64/250/250' }
  ]
});

A disabled entry stays in the results so people can see it exists. A click, Enter and selectOption() all leave it as it is, so no change or expressive:autocomplete fires. Up and Down skip it, and the announced result count leaves it out, so a list of only disabled matches announces i18n.noResults. The selected option and setMenuItems(items, selected) can still select one, which shows a choice the person cannot remove:

Expressive.Autocomplete.init(document.querySelector('#autocomplete-disabled'), {
  minLength: 0,
  isMultiSelect: true,
  selected: ['vienna'],
  data: [
    { id: 'lisbon', text: 'Lisbon' },
    { id: 'oslo', text: 'Oslo', disabled: true },
    { id: 'rome', text: 'Rome' },
    { id: 'vienna', text: 'Vienna', disabled: true }
  ]
});

Give entries a group to list them under labelled headings. Entries with the same group gather where the group first appears in the results, so sort them yourself if the order matters; entries without one stay outside every group. Up and Down pass over a heading to the next entry, the announced result count leaves headings out, and a click on a heading chooses nothing. The heading is plain text, even with allowUnsafeHTML:

Expressive.Autocomplete.init(document.querySelector('#autocomplete-groups'), {
  minLength: 0,
  data: [
    { id: 'lisbon', text: 'Lisbon', group: 'Portugal' },
    { id: 'porto', text: 'Porto', group: 'Portugal' },
    { id: 'bergen', text: 'Bergen', group: 'Norway' },
    { id: 'oslo', text: 'Oslo', group: 'Norway' }
  ]
});

A custom onSearch can load data asynchronously. When the list is ready, call setMenuItems. The default filter looks at id and text only:

onSearch: function(text, autocomplete) {
  const normSearch = text.toLocaleLowerCase();
  autocomplete.setMenuItems(
    autocomplete.options.data.filter(function(option) {
      return option.id.toString().toLocaleLowerCase().includes(normSearch)
        || (option.text && option.text.toLocaleLowerCase().includes(normSearch));
    })
  );
}

The third argument is an AbortSignal. It aborts when the search text changes or the autocomplete is destroyed. Pass it to fetch() so a slow response for old text never replaces the results for the current text. Clear the list on any other error. Set searchDelay so the request waits for typing to pause instead of going out on every key:

searchDelay: 300,
onSearch: function(text, autocomplete, signal) {
  fetch('/api/search?q=' + encodeURIComponent(text), { signal })
    .then(function(response) { return response.json(); })
    .then(function(items) { autocomplete.setMenuItems(items); })
    .catch(function(error) {
      // A newer search aborted this one; its results are stale.
      if (error.name !== 'AbortError') autocomplete.setMenuItems([]);
    });
}

Set allowCreate to offer the typed text as a new value. The list then ends in an "Add" row whenever the trimmed text matches no listed suggestion. The comparison ignores case and checks each suggestion's text, or its id when it has no text. Choosing the row with Enter or a click calls onCreate with the trimmed text and fires expressive:create with { text }. The selection does not change, so add and select the entry yourself:

allowCreate: true,
onCreate: function(text, autocomplete) {
  const entry = { id: text, text: text };
  autocomplete.options.data.push(entry);
  autocomplete.setMenuItems(autocomplete.options.data, [entry.id], false);
}

Options

Methods

All methods are called on the plugin instance. You can get the instance like this:

const instance = Expressive.Autocomplete.getInstance(elem);

.open();

Open the suggestion menu if the input meets minLength.

instance.open();

.close();

Close the suggestion menu.

instance.close();

.selectOption();

Select (or toggle, when multi-select) the entry with this id.

instance.selectOption(42);

.setMenuItems();

Replace the visible suggestions. Optionally pass selected ids and whether to open the menu (default true).

instance.setMenuItems([
  { id: 'Test' },
  { id: 12, text: 'Apple' },
  { id: 13, text: 'Microsoft' },
  { id: 42, text: 'Google', image: 'https://picsum.photos/id/64/250/250' }
]);

.destroy();

Destroy the plugin instance, remove the menu, and detach its event handlers.

instance.destroy();

Properties

Name	Type	Description
el	Element	The input the plugin was initialized with.
options	Object	The options the instance was initialized with.
isOpen	Boolean	Whether the suggestion menu is open.
count	Number	Number of matching options (reset on each input or focus).
activeIndex	Number	Index of the keyboard-highlighted option, or -1.
menu	Menu	The Menu instance for this autocomplete.
selectedValues	Array	The currently selected entries.