@launchscout/autocomplete-input
v0.2.0
Published
A simple, event oriented autocomplete custom element
Downloads
3
Readme
<autocomplete-input>
This custom element implements an autocomplete (aka combobox) input as a form associated custom element. As a form associated element, it will "quack" just like a real input when added to form: it will use its name attribute to populate the FormData of it's surrounding form element.
Motivation
Existing solutions generally expect to manage and filter their own list of options, which is problematic for applications that wish to manage this process from outside the element (eg server side).
This element does not fetch its own list of elements or do filtering based on the input value. Instead, it relies on the surrounding application to provide the current set of options and emits events based on user interaction. This makes it a good fit with event oriented backends such as LiveView or LiveState.
The intended usage pattern for this element is to handle the events dispatched by this element(see below), use the data in said events to obtain the current list of items, and populate the list of items as inner content in the list
slot (see below).
Installation
npm install @launchscout/autocomplete-input
Providing options
This element requires the user to provide the list of options as inner content to the element using the list
named slot. This slot is expected to contain a list of options. Each element with aria-role="option"
will be considered an option. The data-value
property of the selected item will be set as the value in the FormData.
Example:
<autocomplete-input name="company">
<ul slot="list">
<li role="option" data-value="1">Foo Corp</li>
<li role="option" data-value="2">Bar Corp</li>
</ul>
</autocomplete-input>
Alternatively, the list
attribute may be given the DOM id of a list outside the element:
<autocomplete-input name="company" list="company-list">
</autocomplete-input>
<ul id="company-list">
<li role="option" data-value="1">Foo Corp</li>
<li role="option" data-value="2">Bar Corp</li>
</ul>
Events
autocomplete-search
sent when the value of the input changes and is greater than theminlength
, debounced by the specified interval.autocomplete-commit
sent when an item is selected either by pressing Enter or clicking an optionautocomplete-close
sent when the element is open and loses focus, on by user pressing Escape
Attributes
name
This is a required attribute for setting the correct FormData value. It works exactly the same way as thename
attribute of any other form input.clear-list-on-select
If true, will cause the options list to have it's children removed when anautocomplete-commit
event is about to be dispatched.debounce
The time in milliseconds to debounce before sending anautocomplete-search
event when the user enters text into the inputvalue
The value which will be initially used to populate theFormData
of the associated form.searchValue
The value which will initially be used to populate the search input.open
The element will start in the Open mode display the text input
Styling the selected option
The currently selected option (via keyboard navigation) will be so indicated by adding the airia-selected
attribute. This allows you to style the selected option like so:
autocomplete-element [aria-selected='true'] {
background-color: lavender;
}
Example
The index.html
file in this directory shows a simple example of choosing people and adding them to a list. It requires the silly_crm example app to be up and running. It will also only work if you've created Person
s that can be found.
Credits
The excellent @github/combobox-nav provides the functionality to navigate and select from the list of options.