Back to Autocomplete-guidelines

JavaScriptThe latest version of this package is: 0.18.6, Opens in new window

Javascript library for the Autocomplete Component

This component is compatible with ESM (ES6 module) and IIFE. See documentation examples below.

To be able to install this component, please refer to the Project Setup documentation.

View repository, Opens in new windowView package, Opens in new window
$ npm i @ids-js/autocomplete@0.18.6

Table of Contents

Features

  • Matches suggestions and presens a selectable lists with suggestions to use
  • User can traverse suggestions with keyboard (arrows)
  • User can close suggestions by clicking out side of the autocomplete or pressing escape
  • The autocomplete can be string or tag based
  • Customizable trigger for when to trigger a match

Usage

Other relevant components:

Tips: start searching: "how do i.."
  1. how do I convert to pdf
  2. how do I convert to muslim
  3. how do I convert to judaism
  4. how do I convert to christianity
  5. how do I convert to catholic
  6. how do I convert to mp3

Required markup

String

<div class="if input-wrapper autocomplete">
  <input
    type="search"
    class="if input-field"
    name="search"
    placeholder="Enter your search"
    aria-expanded="false"
  />
  <label for="search" class="if"> Search </label>
  <div class="if input-help">Tips: start searching: "how do i.."</div>
  <ol
    id="autocomplete-suggestions-2"
    role="listbox"
    class="if suggestions"
  ></ol>
</div>
By script tag
<!-- Here we've just used a random name -->
<script src="/autocomplete.string.js"></script>
<script>
  const suggestions = [
    'how do i convert to pdf',
    'how do i convert to muslim',
    'how do i convert to judaism',
    'how do i convert to christianity',
    'how do i convert to catholic',
    'how do i convert to mp3',
  ];
  const autocompleteElements = document.querySelectorAll(
    '.if.autocomplete:not(.tags)'
  );
  const callback = (value) => {
    console.log(`Searching for ${value}`);
  };
  autocompleteElements.forEach((el) => {
    autocomplete.initStringAutocomplete(el, {
      suggestions,
      callback,
      charLimit: 3,
    });
  });
</script>
As an ES6 module
import autocomplete from '@if-design-components-javascipt/autocomplete';

const suggestions = [
  'how do i convert to pdf',
  'how do i convert to muslim',
  'how do i convert to judaism',
  'how do i convert to christianity',
  'how do i convert to catholic',
  'how do i convert to mp3',
];
const autocompleteElements = document.querySelectorAll(
  '.if.autocomplete:not(.tags)'
);
const callback = (value) => {
  console.log(`Searching for ${value}`);
};
autocompleteElements.forEach((el) => {
  autocomplete.initStringAutocomplete(el, {
    suggestions,
    callback,
    charLimit: 3,
  });
});

Api

initStringAutocomplete(el, options)

Initializes the autocomplete with the given options.

Param Type Description
el HTMLElement The autocomplete element
options AutocompleteOptions Options for the autocomplete
el : HTMLElement

The autocomplete DOM element:

<div class="if input-wrapper autocomplete">
  <input type="search" class="if input-field" name="search" placeholder="Enter your search" aria-expanded="false" />
  <label for="search" class="if"> Search </label>
  <div class="if input-help">Tips: start searching: "how do i.."</div>
  <ol id="autocomplete-suggestions-2" role="listbox" class="if suggestions"></ol>
</div>
options : AutocompleteOptions Object

A JavaScript object containing options for the autocomplete component.

Type Default
Object { suggestions: [], charLimit: 2 }
Name Type Default Description
suggestions Array/Function [] Either an array of strings to match, or a function returning a promise containing an arra to match
charLimit Number 2
callback Function A callback function that is called after user selects a suggestion. Takes the value of the selected item as an argument.
options.suggestions : Array/Function
Type Default
Array/Function []

This could either be:

A: An array of suggestions, like:

const suggestions = [
  'how do i convert to pdf',
  'how do i convert to muslim',
  'how do i convert to judaism',
  'how do i convert to christianity',
  'how do i convert to catholic',
  'how do i convert to mp3',
];

or B: An async method (must return a promise) that fetches results to use as suggestions:

const suggestions = query =>
  fetch(
    `https://services.odata.org/Northwind/Northwind.svc/Products?$format=json&$select=ProductID%2CProductName&$filter=indexof(ProductName%2C%20%27${query}%27)%20gt%20-1`
  )
    .then(response => response.json())
    .then(products => products.value.map(product => product.ProductName));
};
options.charLimit : Number

A limit on when the autocomplete should start looking for matches. This might come in handy when used with fetch or any asynchronous call.

Type Default value
Number 2

initTagsAutocomplete(el, options)

The initialization and options are the same for initTagsAutocomplete(el, options) as for initStringAutocomplete(el, options). The key difference is the markup:

<div class="if input-wrapper autocomplete tags">
  <input type="text" class="if input-field tag-holder" name="tags" value="Orwell, 1984" />
  <label for="tags" class="if"> Choose tags </label>

  <div class="if autocomplete-tags-input-holder">
    <ol id="autocomplete-suggestions-1" role="listbox" class="if suggestions"></ol>
    <button type="button" data-rel="Orwell" aria-label="Remove Orwell" class="if tag input">Orwell</button>
    <button type="button" data-rel="1984" aria-label="Remove 1984" class="if tag input">1984</button>
    <input
      name="autocomplete-1"
      type="text"
      aria-expanded="false"
      aria-owns="autocomplete-suggestions-1"
      aria-autocomplete="list"
      autocomplete="off"
      role="combobox"
      class="if input-field"
      data-size="largest"
    />
  </div>
  <span class="if input-help">
    Create tags by typing and use comma <kbd class="if">,</kbd> or <kbd class="if">Enter</kbd> to add them
  </span>
</div>

As you can see, you can also put predefined tags into the autocomplete.

Changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

0.17.5 (2021-11-24)

Bug Fixes

0.17.0 (2021-10-21)

Code Refactoring

  • 💡 Remove support for CommonJS (9f84d9a)

BREAKING CHANGES

  • 🧨 We have removed the support for CommonJS for all @ids-js packages

0.16.1 (2021-10-21)

Bug Fixes

  • Use common for cjs and main for esm (96f673d)

0.7.0 (2021-02-23)

Bug Fixes

  • 🐛 Fix clickoutside and tmptags (8b00e60)

Features

  • 🎸 Add autocomplete script (ea15e98)
Contact us, Opens in new window