@trevoreyre/autocomplete-js
Demo
Take a look at the documentation page, and the Codepen examples.
Installation
Install the component from npm.
npm install --save @trevoreyre/autocomplete-js
Or using yarn.
yarn add @trevoreyre/autocomplete-js
You can also use the browser bundle in a script tag.
<script src="https://unpkg.com/@trevoreyre/autocomplete-js"></script>
To add the default styling for the component, include the CSS file on your page as well.
<link
rel="stylesheet"
href="https://unpkg.com/@trevoreyre/autocomplete-js/dist/style.css"
/>
Usage
The JavaScript component expects a fairly simple HTML structure consisting of a root container element, with an input
and ul
children.
<div id="autocomplete" class="autocomplete">
<input class="autocomplete-input" />
<ul class="autocomplete-result-list"></ul>
</div>
The constructor takes two arguments, the root
, and an options
object.
new Autocomplete('#autocomplete', options)
Upon initialization, the component will take care of initializing all of the proper ARIA attributes.
Arguments
Argument | Type | Description |
---|---|---|
root |
String | DOM Element (required) | Either the container DOM element, or a selector for it |
options |
Object | An object of options to pass to the component. See below for more details. |
root
The root
argument can be either a reference to the container DOM element, or a selector for it.
// root can be a DOM element
const root = document.getElementById('autocomplete')
new Autocomplete(root, options)
// or a string selector
new Autocomplete('#autocomplete', options)
Note that if using a selector, it's expected that the selector only matches one DOM element. In the case of a selector that matches multiple elements, the autocomplete component is only attached to the first match. If you need to attach to multiple elements, you will need to loop through them manually.
// Select all of the elements
const elements = document.querySelectorAll('.autocomplete')
const search = input => {
if (input.length < 1) {
return []
}
return countries.filter(country => {
return country.toLowerCase().startsWith(input.toLowerCase())
})
}
// Attach autocomplete to each element
elements.forEach(el => {
new Autocomplete(el, { search })
})
Options
Option | Type | Default | Description |
---|---|---|---|
search |
Function (required) | The search function to be executed on user input. Can be a synchronous function or a Promise . |
|
onSubmit |
Function | Executed on input submission | |
onUpdate |
Function | Executed when the results list is updated | |
baseClass |
String | 'autocomplete' |
Base class used to create classes and IDs for generated DOM elements |
autoSelect |
Boolean | false |
Controls whether first result should be highlighted after input |
getResultValue |
Function | For complex search results, this function is executed to get the value to display in the input | |
debounceTime |
Number | 0 |
Time in milliseconds that the component should wait after last keystroke before calling search function |
renderResult |
Function | Override default rendering of result items |
search
The search
function is executed on user input. It is expected to return either an array of results to be rendered, or a Promise
that resolves to an array of results.
In the simplest case, search
can return an array of strings.
new Autocomplete('#autocomplete', {
search: input => {
if (input.length < 1) {
return []
}
return countries.filter(country => {
return country.toLowerCase().startsWith(input.toLowerCase())
})
},
})
The search
function can also return a Promise
, to make asynchronous calls to an API, for example. The return value doesn't have to be an array of strings, it can also be an array of objects. In this case, you will need to provide a getResultValue
function to get the raw value from your result object to display in the input
field when a user selects or submits a result.
Below is a more advanced search example showing these options.
const wikiUrl = 'https://en.wikipedia.org'
const params = 'action=query&list=search&format=json&origin=*'
new Autocomplete('#autocomplete', {
// Search function can return a promise
// which resolves with an array of
// results. In this case we're using
// the Wikipedia search API.
search: input => {
const url = `${wikiUrl}/w/api.php?${params}&srsearch=${encodeURI(input)}`
return new Promise(resolve => {
if (input.length < 3) {
return resolve([])
}
fetch(url)
.then(response => response.json())
.then(data => {
resolve(data.query.search)
})
})
},
// Wikipedia returns a format like this:
//
// {
// pageid: 12345,
// title: 'Article title',
// ...
// }
//
// We want to display the title
getResultValue: result => result.title,
// Open the selected article in
// a new window
onSubmit: result => {
window.open(`${wikiUrl}/wiki/${encodeURI(result.title)}`)
},
})
onSubmit
The onSubmit
function is executed when the user submits their result by either selecting a result from the list, or pressing enter/return
. The function receives the selected result as an argument.
new Autocomplete('#autocomplete', {
search: input => {
if (input.length < 1) {
return []
}
return countries.filter(country => {
return country.toLowerCase().startsWith(input.toLowerCase())
})
},
onSubmit: result => {
alert(`You selected ${result}`)
},
})
onUpdate
The onUpdate
function is executed when the results list is updated. The function receives the results list and the index of the selected result.
new Autocomplete('#autocomplete', {
search: input => {
if (input.length < 1) {
return []
}
return countries.filter(country => {
return country.toLowerCase().startsWith(input.toLowerCase())
})
},
onUpdate: (results, selectedIndex) => {
console.log(`${results.length} results`)
if (selectedIndex > -1) {
console.log(`Selected: ${results[selectedIndex]}`)
}
},
})
baseClass
The baseClass
option is used to derive classes for generated DOM elements in the results list. It's also used to create IDs when necessary for use in ARIA attributes.
For example, if you passed a baseClass
of 'search'
:
new Autocomplete('.search', { baseClass: 'search' })
You would get the following DOM (simplified for demonstration purposes):
<!-- The root, input, and ul element classes are unaffected by the baseClass option.
- It's expected that you provide these classes in your HTML. The baseClass is used
- to generate an ID for the ul element only if you didn't provide one.
-->
<div class="search">
<input class="search-input" />
<ul id="search-result-list-1" class="search-result-list">
<!-- The ID and class for result list items are generated from the baseClass option -->
<li id="search-result-0" class="search-result">
First result
</li>
<li id="search-result-1" class="search-result">
Second result
</li>
</ul>
</div>
This option can be useful if you need a certain class in your DOM for styling purposes. See the section on Styling and customization for more info.
autoSelect
If the autoSelect
option is set to true
, the first result in the list will automatically be highlighted after user input.
new Autocomplete('#autocomplete', {
search: input => {
if (input.length < 1) {
return []
}
return countries.filter(country => {
return country.toLowerCase().startsWith(input.toLowerCase())
})
},
autoSelect: true,
})
getResultValue
If your search function returns more complex results like an array of objects, you can use the getResultValue
function to tell the autocomplete component what value to display in the results list and input. The function receives a result as an argument, and is expected to return a String
to display for that result.
new Autocomplete('#autocomplete', {
search: input => {
if (input.length < 1) {
return []
}
return animals.filter(animal => {
return animal.name.toLowerCase().startsWith(input.toLowerCase())
})
},
// Results come back in the format:
//
// {
// name: 'lion',
// collateral_adjectives: [
// 'leonine',
// 'lionish'
// ]
// }
//
// We want to display the name
getResultValue: result => result.name,
})
debounceTime
The debounceTime
option can be used to improve the performance of your UI by specifying an amount of time (milliseconds) to wait before invoking the search function. This ensures that the search function will not fire until the user is done typing instead of firing after each keystroke.
new Autocomplete('#autocomplete', {
search: input => {
return searchWikipedia(input)
},
debounceTime: 500,
})
renderResult
You can use the renderResult
function to override the default rendering of items in your result list. This function takes the following arguments:
-
result
- The result value returned from yoursearch
function -
props
- An object containing generated attributes for the result item, which are expected to be set on yourli
element. The object has a customtoString
function which lets you easily serialize it to aString
of HTML attributes in the formattribute1="value1" attribute2="value2"
. This way, you don't have to worry about generating the proper IDs, classes, and ARIA attributes yourself.
The renderResult
function should return either a DOM element or an HTML string.
const wikiUrl = 'https://en.wikipedia.org'
const params = 'action=query&list=search&format=json&origin=*'
new Autocomplete('#autocomplete', {
// Search function can return a promise
// which resolves with an array of
// results. In this case we're using
// the Wikipedia search API.
search: input => {
const url = `${wikiUrl}/w/api.php?${params}&srsearch=${encodeURI(input)}`
return new Promise(resolve => {
if (input.length < 3) {
return resolve([])
}
fetch(url)
.then(response => response.json())
.then(data => {
resolve(data.query.search)
})
})
},
// Control the rendering of the result
// items. Let's show the title and snippet
// from the Wikipedia results
renderResult: (result, props) => `
<li ${props}>
<div class="wiki-title">
${result.title}
</div>
<div class="wiki-snippet">
${result.snippet}
</div>
</li>
`,
// Wikipedia returns a format like this:
//
// {
// pageid: 12345,
// title: 'Article title',
// ...
// }
//
// We want to display the title
getResultValue: result => result.title,
// Open the selected article in
// a new window
onSubmit: result => {
window.open(`${wikiUrl}/wiki/${encodeURI(result.title)}`)
},
})
Styling and customization
To include the default styling of the autocomplete component that you see here in the docs, include the CSS file on your page.
<link
rel="stylesheet"
href="https://unpkg.com/@trevoreyre/autocomplete-js/dist/style.css"
/>
This styling is intentionally opinionated, however, it's relatively easy to write your own CSS if you want a different style. All positional styling is handled inline, so you don't have to worry about positioning the results list in your CSS.
You can provide the IDs and classes for the root element, input
, and ul
elements yourself in your HTML template. IDs and classes for the li
elements are generated for you, but can be customized using the baseClass
option. If you need more control than the baseClass
option can provide, you can also take full control of the rendering of items in your results list using the renderResult
option.
Below is an example of a typical DOM structure, and all the properties that might be relevant for styling.
<div
id="autocomplete"
class="autocomplete"
data-expanded="true"
data-loading="false"
data-position="below"
>
<input class="autocomplete-input" aria-expanded="true" />
<ul id="autocomplete-result-list-1" class="autocomplete-result-list">
<li
id="autocomplete-result-0"
class="autocomplete-result"
data-result-index="0"
aria-selected="true"
>
First result
</li>
<li
id="autocomplete-result-1"
class="autocomplete-result"
data-result-index="1"
>
Second result
</li>
</ul>
</div>
There are a few data attributes that are added to the root element as well to show the current state of the component.
-
data-expanded="true"
- This is added when the results list is open -
data-loading="true"
- This is added if yoursearch
function is aPromise
, and hasn't resolved yet -
data-position="below"
- This shows if the results list is positionedabove
orbelow
theinput
element
In addition, an aria-expanded
attribute is added to the input
element, and aria-selected
is added to the currently selected li
element.
Below is an example of how you could use these attributes in your CSS.
/* Change border if results are above input */
[data-position='above'] .autocomplete-result-list {
border-bottom: none;
border-radius: 8px 8px 0 0;
}