Autocomplete

Autocomplete widget for input elements.

Dependencies

• Circle Loader

How to

The autocomplete component suggests possible results to users while typing in an input field.

You can initialize it using the Autocomplete object:

var autocomplete = document.getElementsByClassName('autocomplete')[0]; // your input element
new Autocomplete({
  element: autocomplete,
  searchData: function(value, cb) {
    // function to return search results
  }
});

Note that in the autocomplete.js, we do not initialize the Autocomplete object. 

You should initialize it, passing, as searchData argument, the function used to retrieve search results (more in the searchData section).

Options #

The Autocomplete comes with a list of options that you can use to customize its behavior:

• debounce: this is the delay between the user stops typing, and the autocomplete starts searching for results. Pass a value in milliseconds (e.g., 300); default value is 200;
• characters: this is the minimum number of characters the user needs to type before the autocomplete starts searching for results; default is 2;
• onClick: function to be executed when the user selects one of the items in the autocomplete dropdown. The arguments of the function are the selected item in the dropdown and the autocomplete object. More in the onClick section;
• searchData: function that is used to retrieve search results (required). The arguments are the query value and a callback function. More in the searchData section.

onClick option #

The onClick option can be used to customize the behavior of your component when a suggestion is selected. Here's an example of how the function could look like:

new Autocomplete({
  element: autocomplete,
  searchData: function(query, cb, eventType) {
    // function here
    cb(data);
  },
  onClick: function(option, obj, event, cb) {
    // obj.input is the autocomplete input
    // option is the <li> element selected by the user
    console.log('User typed '+obj.input.value+'; user selected '+option.textContent);
    // update input value 
    obj.input.value = option.textContent;
    cb(); // close the autocomplete list
  }
});

If no function is passed, on click, the input element's value is set equal to the content of the selected item.

searchData option #

The searchData option is the function used to retrieve results.
For example, if you have a static array of possible results, here's how this function could look like:

// your input field
var autocomplete = document.getElementsByClassName('autocomplete')[0]; 
// static array of results
var searchValues = [
  {label: 'Samantha Jackson'},
  {label: 'Sam Trust'},
  {label: 'Samuel Drake'},
  {label: 'Samala Anderson'},
  {label: 'Samelle Patt'},
  {label: 'Samson Potter'},
  {label: 'Samira Bolt'},
  {label: 'Sammy Curl'}
];
// initialize the Autocomplete object
new Autocomplete({
  element: autocomplete,
  searchData: function(query, cb, eventType) {
    var data = searchValues.filter(function(item){
      // return item if item['label'] contains 'query'
      return item['label'].toLowerCase().indexOf(query.toLowerCase()) > -1;
    });
    // make sure to call the callback function and pass the data array as its argument
    cb(data);
    // eventType can be 'focus' or 'type'
  }
}); 

⚠️ Note: once your results are ready (data array in the example above), make sure to run the cb function and pass those results as the argument. This way the Autocomplete object will know a new list of results is available and will update the UI.

For more info about the results array structure, see the Autocomplete Dropdown structure section.

Autocomplete Dropdown structure #

By default, each item in a suggestion dropdown is a simple <li> item.

<div class="autocomplete position-relative js-autocomplete" data-autocomplete-dropdown-visible-class="autocomplete--results-visible">
  <!-- input here -->

  <div class="autocomplete__results js-autocomplete__results">
    <ul id="autocomplete1" class="js-autocomplete__list">
      <!-- 👇this is the <li> HTML structure used by the Autocomplete object  -->
      <li class="autocomplete__item js-autocomplete__item is-hidden"></li>
    </ul>
  </div>
</div>

You can modify this structure according to your project needs. Make sure you do not remove the .js-autocomplete__item.is-hidden class from the <li> item.

The plugin expects the searchData function to return an array of results, like the one below:

var searchValues = [
  {label: 'Samantha Jackson'},
  {label: 'Sam Trust'}
];

The label key is required. This is used as text content of the <li> element. Alternatively, if you are using a custom structure, and there's a child of the <li> element that has a data-autocomplete-label, the label key will be used as text of this child element.

You can also pass a class key: in this case, the key's value will be treated as a list of classes and added to the <li> item.

var searchValues = [
  {label: 'Samantha Jackson', class: 'bg-primary'},
  {label: 'Sam Trust', class: 'color-primary'}
];

You can pass a url key: the plugin will search for a child of the <li> element with a data-autocomplete-url attribute, and set the href attribute equal to the url value.

As for the url key, you can pass a src key: the plugin will search for a child of the <li> element with a data-autocomplete-src attribute, and set the src attribute equal to the src value.

You can pass additional keys as well: for example, if you pass a category key, the plugin will search for a child of the <li> element with a data-autocomplete-category, and set its content equal to the category key value.

Multiple item templates #

By default, the same HTML structure is used for all of the autocomplete results. If you want to use different result templates, create multiple <li> items with different data-autocomplete-template attributes for each one of them:

<div class="autocomplete position-relative js-autocomplete" data-autocomplete-dropdown-visible-class="autocomplete--results-visible">
  <!-- input here -->

  <div class="autocomplete__results js-autocomplete__results">
    <ul id="autocomplete1" class="js-autocomplete__list">
      <!-- 👇 <li> HTML structure used by the Autocomplete object  -->
      <li data-autocomplete-template="template-1" class="autocomplete__item js-autocomplete__item is-hidden"></li>
      <li data-autocomplete-template="template-2" class="autocomplete__item autocomplete__item--template-2 js-autocomplete__item is-hidden"></li>
    </ul>
  </div>
</div>

When returning the data results, make sure to pass a template key as well:

var searchValues = [
  {label: 'Samantha Jackson', template: 'template-1'},
  {label: 'Sam Trust', template: 'template-2'}
];

Autocomplete Dropdown animation #

The .autocomplete--results-visible class is added to the .autocomplete element to reveal the results dropdown.

You can change this class value (e.g., if you want to change the dropdown entrance animation) using the data-autocomplete-dropdown-visible-class attribute:

<div class="autocomplete position-relative js-autocomplete" data-autocomplete-dropdown-visible-class="autocomplete--results-visible">
  <!-- autocomplete content here -->
</div>

Dropdown height #

The max height of the dropdown element can be modified using the --autocomplete-dropdown-max-height CSS variable (default is 150px).

If you want the max height to change if there's not enough available space, add a data-autocomplete-dropdown-truncate="on" attribute to the .autocomplete element.

<div class="autocomplete" data-autocomplete-dropdown-truncate="on">
  <!-- autocomplete content -->
</div>

Categories

• Forms > Form Elements
• Plugins > Misc

Bug report & feedback

Component Github page ↗