Dynamic Datalist: Autocomplete from an API

HTML’s datalist element provides native autocomplete functionality, but it’s entirely static—you have to know all the options up front. The dynamic-datalist web component solves this by fetching suggestions from an API endpoint as users type, giving you the benefits of native autocomplete with the flexibility of dynamic data.

This component is a modern replacement for my old jQuery predictive typing plugin. I’ve reimagined it as a standards-based web component.

# Basic usage

To use the component, wrap it around your input field and specify an endpoint:

<dynamic-datalist endpoint="/api/search">
  <label for="search">Search
    <input type="text" id="search" name="search"
           placeholder="Type to search..."
           >
  </label>
</dynamic-datalist>

As users type, the component makes GET requests to that endpoint, passing in the typed value as the “query” parameter (e.g., /api/search?query=WHAT_THE_USER_TYPED). The response fromm the endpoint is used to populates a dynamic datalist element with the results.

The structure of the response should be JSON with an options array of string values:

{
  "options": [
    "option 1",
    "option 2",
    "option 3"
  ]
}

# How it works

Under the hood, the component:

1. Adopts (or creates) a datalist element for your input,
2. Listens for “input” events,
3. Debounces requests (waiting at least 250ms) to avoid overwhelming your API,
4. Sends requests to your endpoint with the current value of the input,
5. Reads back the JSON response,
6. Updates the datalist option elements, and
7. Dispatches the update event.

All of this happens transparently—users just see autocomplete suggestions appearing as they type.

# Need POST?

You can change the submission method via the method attribute:

<dynamic-datalist endpoint="/api/lookup" method="post">
  <label for="lookup">Lookup
    <input type="text" id="lookup" name="lookup">
  </label>
</dynamic-datalist>

This sends a POST request with a JSON body: { "query": "..." }. Currently GET and POST are supported, but I could add more if folks want them.

# Custom variable names

As I mentioned, the component uses “query” as the parameter name by default, but you can easily change it via the key attribute:

<dynamic-datalist endpoint="/api/terms" key="term">
  <label for="search">Term search
    <input type="text" id="search" name="term">
  </label>
</dynamic-datalist>

This sends the GET request /api/terms?term=....

# Working with existing datalists

If your input already has a datalist defined, the component will inherit it and replace the existing options with the fetched results, which makes for a nice progressive enhancement:

<dynamic-datalist endpoint="/api/cities">
  <label for="city">City
    <input type="text" id="city" list="cities-list"
           placeholder="Type a city…"
           >
  </label>
  <datalist id="cities-list">
    <option>New York</option>
    <option>Los Angeles</option>
    <option>Chicago</option>
  </datalist>
</dynamic-datalist>

Users see the pre-populated cities immediately, and as they type, API results supplement the list. If JavaScript fails or the web component doesn’t load, users still get the static options. Nothing breaks.

# Event handling

If you want to tap into the component’s event system, it fires three custom events:

• dynamic-datalist:ready - Fired when the component initializes
• dynamic-datalist:update - Fired when the datalist is updated with new options
• dynamic-datalist:error - Fired when an error occurs fetching data

const element = document.querySelector('dynamic-datalist');

element.addEventListener('dynamic-datalist:ready', (e) => {
  console.log('Component ready:', e.detail);
});

element.addEventListener('dynamic-datalist:update', (e) => {
  console.log('Options updated:', e.detail.options);
});

element.addEventListener('dynamic-datalist:error', (e) => {
  console.error('Error:', e.detail.error);
});

Each event provides helpful detail objects with references to the input, datalist, and other relevant data.

# Demo

Check out the demo for live examples (there are also unpkg and ESM builds if you want to test CDN delivery):

# Grab it

The project is available on GitHub. You can also install via npm:

npm install @aarongustafson/dynamic-datalist

If you go that route, there are a few ways to register the element depending on your build setup:

# Option 1: Define it yourself

import { DynamicDatalistElement } from '@aarongustafson/dynamic-datalist';

customElements.define('dynamic-datalist', DynamicDatalistElement);

# Option 2: Let the helper guard registration

import '@aarongustafson/dynamic-datalist/define.js';
// or, when you need to wait:
import { defineDynamicDatalist } from '@aarongustafson/dynamic-datalist/define.js';

defineDynamicDatalist();

# Option 3: Drop the helper in via a <script> tag

<script src="./node_modules/@aarongustafson/dynamic-datalist/define.js" type="module"></script>

Regardless of how you register it, there are no framework dependencies—just clean autocomplete powered by your API. As I mentioned, it’s also available via CDNs, such as unpkg too, if you’d prefer to go that route.