Auto-complete input values from server results

Usage no npm install needed!

<script type="module">
  import githubAutoCompleteElement from 'https://cdn.skypack.dev/@github/auto-complete-element';


<auto-complete> element

Auto-complete input values from server search results.


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



Import as ES modules:

import '@github/auto-complete-element'

With a script tag:

<script type="module" src="./node_modules/@github/auto-complete-element/dist/bundle.js">


<auto-complete src="/users/search" for="users-popup">
  <input type="text">
  <ul id="users-popup"></ul>

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>


  • 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


Network request lifecycle events

Request lifecycle events are dispatched on the <auto-complete> element. These events do not bubble.

  • loadstart - The server fetch has started.
  • load - The network request completed successfully.
  • error - The network request failed.
  • loadend - The network request has completed.

Network events are useful for displaying progress states while the request is in-flight.

const completer = document.querySelector('auto-complete')
const container = completer.parentElement
completer.addEventListener('loadstart', () => container.classList.add('is-loading'))
completer.addEventListener('loadend', () => container.classList.remove('is-loading'))
completer.addEventListener('load', () => container.classList.add('is-success'))
completer.addEventListener('error', () => container.classList.add('is-error'))

Auto-complete events

auto-complete-change is dispatched after a value is selected. In event.detail you can find:

  • relatedTarget: The HTMLInputElement controlling the auto-complete result list.
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


npm install
npm test


Distributed under the MIT license. See LICENSE for details.