Autocomplete Select

Autocomplete Select is a simple and lightweight JavaScript autocomplete widget.

Installation

Install the package:

npm install autocomplete-select
#or
yarn install autocomplete-select

Import the JS and CSS into your code:

import autocomplete from "autocomplete-select";
import "autocomplete-select/autocomplete.css";

Getting Started

At minimum, call the autocomplete() function with the container and onInput options. The input field will be automatically generated inside the container element:

	//These are the objects from which we will choose suggestions
    const countries = [
    	{id: 1, name: "Australia"},
        {id: 2, name: "Bulgaria"},
        //...
        {id: 236, name: "Zambia"}
    ]
    
    const myContainer = document.getElementById(#my-container);
    
    autocomplete({
    	container: myContainer,
        //Filter suggestions based on user query
        onInput: (query, suggestMatches) => {
            const term = query.toLowerCase();
            const matches = countries.filter(country => {
                return ~country.toLowerCase().indexOf(term)
            })
            const formattedMatches = matches.map(match => match.name);
            //call suggestMatches callback with array of matches
        	suggestMatches(formattedMatches)
        }
    })

Once the user selects a suggestion, you may want access the original (unformatted) match object with the onSelect callback. If so, put the formatting logic in the formatMatches option, like so:

	//...
	autocomplete({
    	//...
        onInput: (query, suggestMatches) => {
            const term = query.toLowerCase();
            const unformattedMatches = countries.filter(country => {
                return ~country.toLowerCase().indexOf(term)
            })
            //call suggestMatches callback with array of (unformatted) matches 
        	displayMatches(unformattedMatches)
        },
        formatMatch: (unformattedMatch) => unformattedMatch.name,
        onSelect: (selectedMatch) => {
        	//Here you can do stuff with the unformatted selectedMatch object
        },
        //...
    })

Default behavior

When the user types in the input field, a results panel containing autocomplete suggestions is generated underneath. Besides clicking, the user has the option of using the arrow and Enter keys to navigate the panel and select a suggestion. When a suggestion is selected, the input field is filled with the text of the suggestion.

Options

You can pass the following options to autocomplete()

| Parameter | Type | Description | | :-------: | :---:| ----------- | |container (Required)|HTMLElement|This is the HTMLElement container in which the input element will be generated.| |onInput (Required)| Function(query, suggestMatches)| This function is called when the user types in the input field in order to generate autocomplete suggestions. The first parameter is the current value of the input field. The second parameter is a callback function which should be called with an array of matches to be displayed as autocomplete suggestions.| |formatMatch|Function(match) | This function is run for every match generated by onInput. It should return a String or an HTMLElement which will be used as the formatted autocomplete suggestion. If this function is not provided, the match item itself will be used as the suggestion.| |clearBtnEnabled| Boolean| Provides a button to the right of the input field that will clear the field. The button is only present when the input field is not empty. This option also causes the input value to revert to last selected item when the input field loses focus. The default value is false.| |onClear|Function| This function will be called when the input is cleared (either with the clear button or manually with backspace) | |onSelect|Function(selectedMatch)| This function will be called when the user selects a suggestion (either by clicking on a suggestion or by hitting the Enter key). The parameter is the match item provided by onInput| |initialValue|String| Sets an autofill value for the input field. | |placeholder|String| Sets a placeholder value for the input field.| |name|String| Sets the name attribute for the input field.| |debug|Boolean| Keeps the results open onBlur for development purposes|

CSS

The autocomplete.css import provides very minimal styling to position the results panel, highlight the active suggestion, etc. To add your own styling (which you will definitely want to do!), import a CSS file after this autocomplete.css.

Selectors

| Class | Element | | :---: | ------- | |.autocomplete-input | The auto-generated input element | |.autocomplete-results| The div for the autocomplete suggestion panel | | .active | The suggestion that is currently active |

License

Autocomplete Select is released under the MIT License.