Autocomplete API
const autocomplete = document.querySelector('awc-autocomplete');TypeScript
The selection mode (single vs. multiple) determines the type of value and selection and the arguments removeValue accepts, and the source (local vs. ajax) determines whether setValue requires the text argument and whether setOptions and addOption take any. TypeScript resolves these automatically when you narrow on the multiple and ajax properties:
const autocomplete = document.querySelector('awc-autocomplete')!;
if (autocomplete.multiple) {
autocomplete.value; // string[]
autocomplete.selection; // { value, text }[]
autocomplete.removeValue('1'); // value argument is required
} else {
autocomplete.value; // string
autocomplete.selection; // { value, text } | null
autocomplete.removeValue(); // no argument
}
if (autocomplete.ajax) {
autocomplete.setValue('1', 'One'); // text is required
autocomplete.setOptions([{ value: '1', text: 'One' }]); // ✗ type error
} else {
autocomplete.setValue('1'); // text is optional
autocomplete.setOptions([{ value: '1', text: 'One' }]);
}If you already know the mode at the call site, pass the exported type to querySelector instead of narrowing:
import type {
MultipleAutocompleteElement,
SingleAutocompleteElement,
} from '@ambiki/impulse-view-components/autocomplete';
const multi = document.querySelector<MultipleAutocompleteElement>('awc-autocomplete')!;
multi.value; // string[]
const single = document.querySelector<SingleAutocompleteElement>('awc-autocomplete')!;
single.value; // stringIf you already know the source at the call site, you can also pass the exported type to querySelector instead of narrowing on ajax:
import type {
AjaxAutocompleteElement,
LocalAutocompleteElement,
} from '@ambiki/impulse-view-components/autocomplete';
const ajax = document.querySelector<AjaxAutocompleteElement>('awc-autocomplete')!;
ajax.setValue('1', 'One'); // text is required
ajax.setValue('1'); // ✗ type error
const local = document.querySelector<LocalAutocompleteElement>('awc-autocomplete')!;
local.setValue('1'); // text is optionalEach alias leaves the other dimension open, but they are composable — pass the other dimension as a type argument to pin both at once:
const el = document.querySelector<MultipleAutocompleteElement<'ajax'>>('awc-autocomplete')!;
el.value; // string[]
el.setValue('1', 'One'); // text is required
// `AjaxAutocompleteElement<'multiple'>` resolves to the same type.Properties
open
Whether the listbox is open. Setting it, or adding or removing the open attribute, shows or hides the listbox as show and hide do. A removed autocomplete keeps open, and opens its listbox again when it's added back.
autocomplete.open;
// => false
autocomplete.open = true;value
The selected value(s). For a single select this is a string; for a multiple select it is a string[].
// Multiple select
autocomplete.value;
// => ['1', '2']
// Single select
autocomplete.value;
// => '1'selection
Each selected value with its text. For a single select this is one { value, text }, or null when nothing is selected; for a multiple select it is an array in the order of value. The text is the committed one, not what the user is typing.
// Multiple select
autocomplete.selection;
// => [{ value: '1', text: 'Apple' }, { value: '2', text: 'Banana' }]
// Single select
autocomplete.selection;
// => { value: '1', text: 'Apple' }multiple
Whether multiple values can be selected. Narrowing on this resolves mode-dependent types — see TypeScript.
autocomplete.multiple;
// => trueajax
Whether the options are fetched from the server (i.e. the src attribute is set). Narrowing on this resolves source-dependent types — see TypeScript.
autocomplete.ajax;
// => trueactiveOption
The option that has the data-active attribute.
autocomplete.activeOption;visibleOptions
All the visible options of the autocomplete element.
autocomplete.visibleOptions;options
All the options of the autocomplete element.
autocomplete.options;form
The parent form element.
autocomplete.form;Methods
show
Shows the listbox. Emits awc-autocomplete:shown, but not the cancelable awc-autocomplete:show.
autocomplete.show();hide
Hides the listbox. Emits awc-autocomplete:hidden, but not the cancelable awc-autocomplete:hide.
await autocomplete.hide();requestShow
Shows the listbox as if the user asked to. Emits a cancelable awc-autocomplete:show, and does nothing if it is prevented.
autocomplete.requestShow();requestHide
Hides the listbox as if the user asked to. Emits a cancelable awc-autocomplete:hide, and does nothing if it is prevented.
await autocomplete.requestHide();setValue
Sets the value of the element. When the options are fetched from the server, the text argument is required (the option is not in the DOM, so its text cannot be derived); for local options it is optional. See TypeScript for how to enforce this at compile time.
// Multiple select
autocomplete.setValue('apple', 'Apple');
autocomplete.value;
// => ['apple']
// When the options are not loaded from the server, you do not have to pass the text argument.
autocomplete.setValue('apple');
autocomplete.value;
// => ['apple']removeValue
Removes a value from the element.
// Multiple select
autocomplete.removeValue('apple');
autocomplete.value;
// => []TIP
The value argument is required for a multiple select and is not used by a single select (which clears its value when removeValue() is called). TypeScript enforces this when the mode is known — see TypeScript.
setOptions
Replaces the options. Each takes a value and a text, and optionally a description and disabled. A group takes a title and its options, and sits among the options; groups don't nest. A selected value that no option offers any longer is deselected, with nothing selected in its place, and one that an option still offers takes that option's text. Not for an ajax select, whose options come from the server.
autocomplete.setOptions([
{ value: 'apple', text: 'Apple' },
{ value: 'kiwi', text: 'Kiwi', description: 'Out of season', disabled: true },
{ title: 'Berries', options: [{ value: 'cherry', text: 'Cherry' }] },
]);addOption
Adds an option after the others, and returns it. It takes what each option of setOptions does. Not for an ajax select.
const option = autocomplete.addOption({ value: 'mango', text: 'Mango' });activate
Activates an option by setting the data-active attribute, and scrolls it into view. Pass { scroll: false } to skip the scrolling.
const option = autocomplete.options[0];
autocomplete.activate(option, { scroll: false });deactivate
Deactivates the active option by removing the data-active attribute.
autocomplete.deactivate();clear
Deselects all the selected options.
autocomplete.clear();reset
Resets the autocomplete value to its initial state. In a local select, only the values an option still offers come back.
autocomplete.reset();focus
Sets the focus on the input element. It also accepts the native focus options object.
autocomplete.focus({ preventScroll: true });blur
Removes keyboard focus from the input element.
autocomplete.blur();reposition
Positions the listbox straight away. Does nothing while the listbox is closed.
await autocomplete.reposition();Events
Events work as they do on native elements. A user action (pressing the control or typing in the input, Escape, Alt+ArrowDown, Alt+ArrowUp, an outside click, the input losing focus, committing an option in a single select, clearing), or a requestShow or requestHide call, first emits a cancelable show or hide; calling preventDefault() on it keeps the listbox closed or open. show(), hide() and changing open act directly and emit no show or hide, and neither does closing because the form was reset. shown and hidden fire after every open and close. Connecting, moving and removing the element emit nothing.
Like the other events, show and hide bubble. A listener on an element that contains other autocompletes receives their show and hide too, so check event.target before preventing one.
Like input and change, commit, clear, remove and reset fire after the value has changed, and only when the user changed it or the form reset: setValue, removeValue, clear, reset, setOptions and addOption called from code emit nothing.
commit reports the option's state after the commit in event.detail.selected: true when the commit selected it, false when it deselected it in a multiple select.
autocomplete.addEventListener('awc-autocomplete:commit', (event) => {
const { value, selected } = event.detail;
console.log(selected ? `Selected ${value}` : `Deselected ${value}`);
});WARNING
In a single select, committing the option that is already selected emits commit with selected: true, although the value doesn't change. A future release will stop emitting it, as a native <select> emits no change when the user selects the option that is already selected (#310).
| Name | Bubbles | Cancelable | Description |
|---|---|---|---|
awc-autocomplete:show | true | true | Fires before the listbox opens for a user action or requestShow. |
awc-autocomplete:shown | true | false | Fires after the listbox has opened. |
awc-autocomplete:hide | true | true | Fires before the listbox closes for a user action or requestHide. |
awc-autocomplete:hidden | true | false | Fires after the listbox has closed. |
awc-autocomplete:commit | true | false | Fires when the user commits an option. event.detail carries the option as target, its value, its text, and selected: whether the option is selected after the commit. |
awc-autocomplete:clear | true | false | Fires when the user deselects all the options with the clear button. |
awc-autocomplete:remove | true | false | Fires when the user removes a tag. event.detail carries the tag as target, its value, and its text. |
awc-autocomplete:reset | true | false | Fires when the parent form has been reset. |
loadstart | false | false | Fires when the autocomplete starts the network request. |
load | false | false | Fires when the autocomplete fetches the options successfully from the server. |
error | false | false | Fires when the autocomplete fails to fetch the options from the server. |
loadend | false | false | Fires when the autocomplete finishes the network request. |
The commit and remove details are exported as AwcAutocompleteCommitEvent and AwcAutocompleteRemoveEvent from @ambiki/impulse-view-components/autocomplete.