Accessible Autocomplete Component In Vanilla JavaScript – Autocomplete

Preview:

Description:

A fast, dynamic, accessible (WAI-ARIA) compliant autocomplete component written in vanilla JavaScript.

It is highly customizable via CSS and supports asynchronous data fetching.

Also can be used as a component for Vue.js apps.

Basic usage:

Install & Download.

# Yarn
$ yarn add @trevoreyre/autocomplete-js
# NPM
$ npm install @trevoreyre/autocomplete-js --save

Or include the stylesheet and JavaScript from a CDN.

<link rel="stylesheet" href="https://unpkg.com/@trevoreyre/autocomplete-js/dist/style.css">
<script src="https://unpkg.com/@trevoreyre/autocomplete-js"></script>

Create an input field and an empty result list for the autocomplete component.

<div id="autocomplete" class="autocomplete">
  <input class="autocomplete-input"
    placeholder="Search for a country"
    aria-label="Search for a country"
  >
  <ul class="autocomplete-results"></ul>
</div>

Initialize the component and specify the target container element.

new Autocomplete('#autocomplete', {
    // options here
}

Use the search function to load and live search the data. Can be a synchronous function or a Promise.

window['countries'] = [
  'Afghanistan',
  'Albania',
  'Algeria',
  'Andorra',
  ...
]

new Autocomplete('#autocomplete', {
    search: input => {
      if (input.length < 1) { return [] }
      return countries.filter(country => {
        return country.toLowerCase()
          .startsWith(input.toLowerCase())
      })
    }
})

More options & functions to customize the autocomplete component.

new Autocomplete('#autocomplete', {
    // fired on submit
    onSubmit: Function,
    // fired on update
    onUpdate: Function,
    // CSS class
    baseClass: 'autocomplete'
    // highlights the first result
    autoSelect: false,
    // aria-label or aria-labelledby for result list
    resultListLabel: '',
    // immediately call onSubmit on result when pressing Enter
    submitOnEnter: false,
    // executed to get the value of results
    getResultValue: Function,
 
    // overrides default rendering of results list
    renderResults: Function  
}

Changelog:

v3.0.3 (09/10/2024)

• Fixed hydration warnings in SSR by generating id with Vue 3.5 useId function
• Updated dependencies

v3.0.2 (04/04/2024)

• Fixed class and style attributes not rendered on root tag to preserve Vue 2.x inheritAttrs behaviour.

v3.0.1 (04/02/2024)

• Updated storybook to v8.0. Updated stories to new format
• Updated dev dependencies
• BREAKING: Updated node.js version to 18 (newer versions untested)
• BREAKING: Updated vue component for Vue.js 3.x

v2.4.1 (01/17/2023)

• Prevent default action (i. e. form submit) when selecting an entry from result list with Enter while submitOnEnter: false

v2.4.0 (01/10/2023)

• Added submitOnEnter option to control whether or not results should be submitted immediately after selecting them by pressing Enter
• Added resultListLabel option to provide aria-label or aria-labelledby attribute for result list

v2.3.0 (11/03/2020)

• Fixed W3C validation error regarding the attribute autocorrect by changing it to be optional

v2.2.0 (02/29/2020)

• Added onUpdate event when the results list is updated

v2.1.1 (02/29/2020)

• Updated dev dependencies

v2.1.0 (01/11/2020)

• Added debounceTime prop for async search functions

v2.0.4 (12/28/2019)

• Fix: Reverted back to autocomplete=”off” to disable browser auto-fill
• Fix: Set autocomplete attribute to “disabled-autocomplete” to disable auto-fill in Chrome

v2.0.2 (06/29/2019)

• Fix: Include extra attributes in inputProps when using default slot
• Fix: Compute aria-activedescendant attribute properly
• Changed default class for results list from autocomplete-results to autocomplete-result-list
• Changed default ID for results list from autocomplete-results-{id} to autocomplete-result-list-{id}
• Call search function on focus
• Removed renderResults option and replaced with renderResult, which can be used to control rendering of a single result item. This function can return either a DOM element or an HTML string.

v1.0.2 (05/02/2019)

• Added support for input events in Vue component.