Skip to content

Commit 77d73b7

Browse files
aarongustafsonaarongustafson
committed
New post: Dynamic Datalist component
1 parent f44403e commit 77d73b7

File tree

2 files changed

+181
-211
lines changed

2 files changed

+181
-211
lines changed

‎src/_drafts/dynamic-datalist-autocomplete-from-an-api.md‎

Lines changed: 0 additions & 211 deletions
This file was deleted.

‎src/posts/2025-12-16-dynamic-datalist-autocomplete-from-an-api.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: "Dynamic Datalist: Autocomplete from an API"
3+
date: 2025-12-16 19:46:29 +00:00
4+
comments: true
5+
tags: ["forms", "HTML", "JavaScript", "progressive enhancement", "web components", "web forms", "API"]
6+
description: "The `datalist` element is great for autocomplete, but it's static. The `dynamic-datalist` web component brings dynamic, API-driven suggestions to your text fields as users type."
7+
twitter_text: "Want API-driven autocomplete suggestions in your forms? Here’s a web component that makes it happen."
8+
series:
9+
name: "Modern Web Form Best Practices"
10+
tag: "series-forms"
11+
ordinal: "9"
12+
---
13+
14+
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.
15+
16+
<!-- more -->
17+
18+
This component is a modern replacement for [my old jQuery predictive typing plugin](https://github.com/easy-designs/jquery.easy-predictive-typing.js). I’ve reimagined it as a standards-based web component.
19+
20+
## Basic usage
21+
22+
To use the component, wrap it around your `input` field and specify an endpoint:
23+
24+
```html
25+
<dynamic-datalist endpoint="/api/search">
26+
<label for="search">Search
27+
<input type="text" id="search" name="search"
28+
placeholder="Type to search..."
29+
>
30+
</label>
31+
</dynamic-datalist>
32+
```
33+
34+
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.
35+
36+
The structure of the response should be JSON with an `options` array of string values:
37+
38+
```json
39+
{
40+
"options": [
41+
"option 1",
42+
"option 2",
43+
"option 3"
44+
]
45+
}
46+
```
47+
48+
## How it works
49+
50+
Under the hood, the component:
51+
52+
1. Adopts (or creates) a `datalist` element for your `input`,
53+
2. Listens for "input" events,
54+
3. Debounces requests (waiting at least 250ms) to avoid overwhelming your API,
55+
4. Sends requests to your endpoint with the current value of the `input`,
56+
5. Reads back the JSON response,
57+
6. Updates the `datalist` `option` elements, and
58+
7. Dispatches the update event.
59+
60+
All of this happens transparently—users just see autocomplete suggestions appearing as they type.
61+
62+
## Need POST?
63+
64+
You can change the submission method via the `method` attribute:
65+
66+
```html
67+
<dynamic-datalist endpoint="/api/lookup" method="post">
68+
<label for="lookup">Lookup
69+
<input type="text" id="lookup" name="lookup">
70+
</label>
71+
</dynamic-datalist>
72+
```
73+
74+
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.
75+
76+
## Custom variable names
77+
78+
As I mentioned, the component uses "query" as the parameter name by default, but you can easily change it via the `key` attribute:
79+
80+
```html
81+
<dynamic-datalist endpoint="/api/terms" key="term">
82+
<label for="search">Term search
83+
<input type="text" id="search" name="term">
84+
</label>
85+
</dynamic-datalist>
86+
```
87+
88+
This sends the GET request `/api/terms?term=...`.
89+
90+
## Working with existing datalists
91+
92+
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:
93+
94+
```html
95+
<dynamic-datalist endpoint="/api/cities">
96+
<label for="city">City
97+
<input type="text" id="city" list="cities-list"
98+
placeholder="Type a city…"
99+
>
100+
</label>
101+
<datalist id="cities-list">
102+
<option>New York</option>
103+
<option>Los Angeles</option>
104+
<option>Chicago</option>
105+
</datalist>
106+
</dynamic-datalist>
107+
```
108+
109+
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.
110+
111+
## Event handling
112+
113+
If you want to tap into the component’s event system, it fires three custom events:
114+
115+
- `dynamic-datalist:ready` - Fired when the component initializes
116+
- `dynamic-datalist:update` - Fired when the `datalist` is updated with new options
117+
- `dynamic-datalist:error` - Fired when an error occurs fetching data
118+
119+
```javascript
120+
const element = document.querySelector('dynamic-datalist');
121+
122+
element.addEventListener('dynamic-datalist:ready', (e) => {
123+
console.log('Component ready:', e.detail);
124+
});
125+
126+
element.addEventListener('dynamic-datalist:update', (e) => {
127+
console.log('Options updated:', e.detail.options);
128+
});
129+
130+
element.addEventListener('dynamic-datalist:error', (e) => {
131+
console.error('Error:', e.detail.error);
132+
});
133+
```
134+
135+
Each event provides helpful `detail` objects with references to the `input`, `datalist`, and other relevant data.
136+
137+
## Demo
138+
139+
Check out [the demo](https://aarongustafson.github.io/dynamic-datalist/demo/) for live examples (there are also [unpkg](https://aarongustafson.github.io/dynamic-datalist/demo/unpkg.html) and [ESM](https://aarongustafson.github.io/dynamic-datalist/demo/esm.html) builds if you want to test CDN delivery):
140+
141+
<figure id="fig-2025-12-06-03" class="media-container">
142+
<fullscreen-control class="talk__slides__embed video-embed__video">
143+
<iframe src="https://aarongustafson.github.io/dynamic-datalist/demo/" class="talk__slides__embed video-embed__video" frameborder="0"></iframe>
144+
</fullscreen-control>
145+
</figure>
146+
147+
## Grab it
148+
149+
The project is available on [GitHub](https://github.com/aarongustafson/dynamic-datalist). You can also install via npm:
150+
151+
```bash
152+
npm install @aarongustafson/dynamic-datalist
153+
```
154+
155+
If you go that route, there are a few ways to register the element depending on your build setup:
156+
157+
### Option 1: Define it yourself
158+
159+
```javascript
160+
import { DynamicDatalistElement } from '@aarongustafson/dynamic-datalist';
161+
162+
customElements.define('dynamic-datalist', DynamicDatalistElement);
163+
```
164+
165+
### Option 2: Let the helper guard registration
166+
167+
```javascript
168+
import '@aarongustafson/dynamic-datalist/define.js';
169+
// or, when you need to wait:
170+
import { defineDynamicDatalist } from '@aarongustafson/dynamic-datalist/define.js';
171+
172+
defineDynamicDatalist();
173+
```
174+
175+
### Option 3: Drop the helper in via a `<script>` tag
176+
177+
```html
178+
<script src="./node_modules/@aarongustafson/dynamic-datalist/define.js" type="module"></script>
179+
```
180+
181+
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.

0 commit comments

Comments
 (0)