Autocomplete

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

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

<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 — display label. The default search matches id and text.
• image — image URL. Shown as a circle; not searched by default.
• description — optional secondary line under the label.

Extra properties are ignored by the default search. 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' }
  ]
});

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));
    })
  );
}

Options

Name	Type	Default	Description
data	Array	[]	Suggestion list. Each item needs an id; text, image, and description are optional.
isMultiSelect	Boolean	false	If true, several values can be selected. onAutocomplete receives an array.
maxMenuHeight	String	'300px'	Max height of the suggestion menu.
onAutocomplete	Function	null	Called after a selection (and when a default value is applied). Receives the selected entries.
onSearch	Function	filters id and text	Called when the input text changes. Load or filter data, then call setMenuItems.
minLength	Number	1	Characters required before suggestions open. 0 shows the list on click or focus.
menuOptions	Object	see note	Options for Menu. Defaults include autoFocus: false, closeOnClick: false, and coverTrigger: false.
allowUnsafeHTML	Boolean	false	If true, matched text is inserted as HTML. Only use sanitized data.
selected	Array	[]	Initial selected ids (strings or numbers).

Methods

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

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

.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 tear down 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 keyup/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.