Any source, any shape
A URL, an async function or a local array, or several at once as labelled sections. mapResponse, getId, getLabel and getValue adapt whatever shape your data has.
Turn any text input into an accessible combobox over your endpoint, a function or a local list, with sections, recent searches, debounce and cancellation built in.
Cities, commands or people. Your data, one keystroke away.
npm install @samline/autocompleteZero dependenciesTypeScript readyMIT licensed
Nothing selected yet.
ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.
A URL, an async function or a local array, or several at once as labelled sections. mapResponse, getId, getLabel and getValue adapt whatever shape your data has.
ARIA combobox and listbox roles, labelled groups for sections, aria-activedescendant and a live region that announces results, with Arrow keys, Home, End, Enter, Escape and Tab.
Searches are debounced, superseded requests aborted and results cached per query. If one section fails, the others still show. Closing the list cancels the pending search.
Import createAutocomplete as ESM or CommonJS, or load the browser bundle: it mounts every input[data-autocomplete] without writing JavaScript.
subscribe(), on() and bubbling DOM events keep your framework and form in sync. beforeSearch, transformSuggestions, beforeSelect and plugins reshape every step.
An optional stylesheet themed with CSS custom properties, highlighted matches, and a list that flips above the field or joins the top layer as a popover.
Import the package with a bundler or load the browser bundle with a script tag; both return the same controller.
Package / ESM
createAutocomplete, createSearch for headless rendering, the source, cache, recent and highlight helpers and types, as ESM or CommonJS.
HTML / CDN
Mounts input[data-autocomplete] on load and as inputs appear, plus newAutocomplete(), getAutocomplete() and destroyAutocomplete() keyed by input id.
Controller
Renders the popup after your input and returns search(), setValue(), getState(), subscribe(), on(), close(), clear() and more.
Cleanup
Aborts pending work, removes the popup and listeners, and restores the input.
Types
Typed options, controller and event details for your own suggestion type.
Styles
Optional stylesheet; theme it with --autocomplete-* custom properties.
Attach the combobox to an input and point it at your endpoint.
Read the installation guideInstall
npm
npm install @samline/autocompletepnpm
pnpm add @samline/autocompleteyarn
yarn add @samline/autocompletebun
bun add @samline/autocompleteHTML / CDN
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@samline/autocomplete@3.0.0/dist/style.css">
<script src="https://cdn.jsdelivr.net/npm/@samline/autocomplete@3.0.0/dist/browser/autocomplete.global.js" defer></script>Add markup
Keep your label and input. The wrapper needs position: relative so the list can sit under the field.
<div class="field" style="position: relative">
<label for="city">City</label>
<input id="city" type="text">
</div>Create the autocomplete
import { createAutocomplete } from '@samline/autocomplete'
import '@samline/autocomplete/style.css'
createAutocomplete('#city', {
endpoint: '/api/cities',
getId: city => city.id,
getLabel: city => city.name,
onSelect: city => console.log('Selected', city),
})window.Autocomplete.newAutocomplete({
id: 'city',
options: {
endpoint: '/api/cities',
getId: city => city.id,
getLabel: city => city.name,
onSelect: city => console.log('Selected', city),
},
})Load the CDN stylesheet and script from step 1, then load this file with defer after the runtime script.
Continue with every option, the controller, hooks and events.
Explore the optionsThree common integrations, built from the same options. More in the recipes guide.
createAutocomplete('#city', {
endpoint: query => `/api/search?term=${encodeURIComponent(query)}`,
queryParam: null,
mapResponse: payload => payload.data.items,
getLabel: item => item.title,
})The input shows the label while a hidden field submits the id.
Read the optionsconst city = createAutocomplete('#city', {
endpoint: '/api/cities',
getId: city => city.id,
getLabel: city => city.name,
hiddenInput: 'city_id',
})
// Editing a saved record:
city.setValue({ id: 42, name: 'Guadalajara' })Group several sources under labels and bring back recent picks.
Read the recipescreateAutocomplete('#palette', {
sections: [
{ id: 'actions', label: 'Actions', source: actions },
{ id: 'pages', label: 'Pages', source: query => searchPages(query) },
],
minLength: 1,
recent: true,
popover: true,
})?q=<query> by default, and mapResponse reads whatever JSON comes back. No endpoint? Pass a source: any async function, or a local array filtered in the browser without regard to case or accents.<input data-autocomplete="/api/cities"> is a working search. Pin the version in production.createAutocomplete(), read its state with subscribe() and getState(), which fit React’s useSyncExternalStore, and call destroy() on unmount. There is no adapter to install and no peer dependency to ship.createSearch() runs the same pipeline without any DOM: sources, sections, local filtering, caching and partial failures. You render the results and own the ARIA and keyboard support.combobox that controls a listbox. ArrowUp and ArrowDown move through options, Home and End jump to the ends, Enter selects, and Escape or Tab close the list. Result counts, empty results and errors are announced through a live region. Your page supplies the visible label.--autocomplete-* custom properties or target [data-autocomplete-popup] and [data-autocomplete-option], and matches through [data-autocomplete-highlight]. renderOption appends your own DOM nodes to each option, never HTML strings.close() hides the list and cancels the pending search; the controller stays usable. Call destroy() when the input leaves the page: it aborts any request, removes the list and listeners, and restores the input attributes it changed.Follow the first steps, or read the source on GitHub.
Installation, practical guides and the complete API for Autocomplete 3.0.0.
Read the documentation