/auto-complete-element

Auto-complete input values from server search results.

Primary LanguageJavaScriptMIT LicenseMIT

<auto-complete> element

Auto-complete input values from server search results.

Installation

$ npm install --save @github/auto-complete-element

Usage

import '@github/auto-complete-element'
<auto-complete src="/users/search" aria-owns="users-popup">
  <input type="text">
  <ul id="users-popup"></ul>
</auto-complete>

The server response should include the items that matched the search query.

<li role="option">Hubot</li>
<li role="option">Bender</li>
<li role="option">BB-8</li>
<li role="option" aria-disabled="true">R2-D2 (powered down)</li>

The data-autocomplete-value attribute can be used to define the value for an item whose display text needs to be different:

<li role="option" data-autocomplete-value="bb8">BB-8 (astromech)</li>

Attributes

  • open is true when the auto-complete result list is visible
  • value is the selected value from the list or the empty string when cleared

Events

const completer = document.querySelector('auto-complete')

// Network request lifecycle events.
completer.addEventListener('loadstart', function(event) {
  console.log('Network request started', event)
})
completer.addEventListener('loadend', function(event) {
  console.log('Network request complete', event)
})
completer.addEventListener('load', function(event) {
  console.log('Network request succeeded', event)
})
completer.addEventListener('error', function(event) {
  console.log('Network request failed', event)
})

// Auto-complete result events.
completer.addEventListener('auto-complete-change', function(event) {
  console.log('Auto-completed value chosen or cleared', completer.value)
  console.log('Related input element', event.relatedTarget)
})

Browser support

Browsers without native custom element support require a polyfill.

  • Chrome
  • Firefox
  • Safari
  • Microsoft Edge

Development

npm install
npm test

License

Distributed under the MIT license. See LICENSE for details.