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.
$ 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:
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
- use correct params (3a725ff)
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)