Type. Pick. Done.

Autocomplete
Search that feels right.

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/autocomplete

Zero dependenciesTypeScript readyMIT licensed

Autocomplete previewLive preview

Nothing selected yet.

ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.

JavaScript TypeScript React Vue Svelte Shopify WordPress
01 / More than a dropdown

Every detail handled.
Your data, your markup.

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.

An accessible combobox

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.

No stale results

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.

Package, script tag or attributes

Import createAutocomplete as ESM or CommonJS, or load the browser bundle: it mounts every input[data-autocomplete] without writing JavaScript.

State, hooks and plugins

subscribe(), on() and bubbling DOM events keep your framework and form in sync. beforeSearch, transformSuggestions, beforeSelect and plugins reshape every step.

Styled with variables

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.

02 / Fit it into your stack

Two ways in. One controller.

Import the package with a bundler or load the browser bundle with a script tag; both return the same controller.

Package / ESM

@samline/autocomplete

createAutocomplete, createSearch for headless rendering, the source, cache, recent and highlight helpers and types, as ESM or CommonJS.

HTML / CDN

window.Autocomplete

Mounts input[data-autocomplete] on load and as inputs appear, plus newAutocomplete(), getAutocomplete() and destroyAutocomplete() keyed by input id.

Controller

createAutocomplete(input, options)

Renders the popup after your input and returns search(), setValue(), getState(), subscribe(), on(), close(), clear() and more.

Cleanup

controller.destroy()

Aborts pending work, removes the popup and listeners, and restores the input.

Types

AutocompleteOptions<T>

Typed options, controller and event details for your own suggestion type.

Styles

@samline/autocomplete/style.css

Optional stylesheet; theme it with --autocomplete-* custom properties.

03 / Install and search

One install. One working search.

Attach the combobox to an input and point it at your endpoint.

Read the installation guide
1

Install

npm

Terminal
npm install @samline/autocomplete

pnpm

Terminal
pnpm add @samline/autocomplete

yarn

Terminal
yarn add @samline/autocomplete

bun

Terminal
bun add @samline/autocomplete

HTML / CDN

Terminal
<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>
2

Add markup

Keep your label and input. The wrapper needs position: relative so the list can sit under the field.

index.html
<div class="field" style="position: relative">
  <label for="city">City</label>
  <input id="city" type="text">
</div>
3

Create the autocomplete

main.js
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),
})
main.js
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.

Copy complete working files

Continue with every option, the controller, hooks and events.

Explore the options
04 / Beyond the first search

Adapt any API.
Keep the form in sync.

Three common integrations, built from the same options. More in the recipes guide.

mapResponse

Map any response

Turn your API payload into a list of suggestions.

Read the options
main.js
createAutocomplete('#city', {
  endpoint: query => `/api/search?term=${encodeURIComponent(query)}`,
  queryParam: null,
  mapResponse: payload => payload.data.items,
  getLabel: item => item.title,
})
hiddenInput

Submit the selected id

The input shows the label while a hidden field submits the id.

Read the options
main.js
const 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' })
sections

Build a command palette

Group several sources under labels and bring back recent picks.

Read the recipes
main.js
createAutocomplete('#palette', {
  sections: [
    { id: 'actions', label: 'Actions', source: actions },
    { id: 'pages', label: 'Pages', source: query => searchPages(query) },
  ],
  minLength: 1,
  recent: true,
  popover: true,
})
Explore working examples
05 / Before you build

A few details. Clearly answered.

Does it work with my backend?
Yes. It requests any URL or function you provide, adding ?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.
Does it work without a bundler?
Yes. The HTML / CDN script mounts every input with a data-autocomplete attribute, in plain HTML, WordPress or Shopify: <input data-autocomplete="/api/cities"> is a working search. Pin the version in production.
Can I use it with React, Vue or Svelte?
Yes. Pass the mounted input from a ref to 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.
Can I render the results myself?
Yes. 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.
How does it handle accessibility?
The input becomes an ARIA 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.
What happens to slow responses?
Each new search aborts the previous request and older responses are ignored. Closing the list also cancels the pending search, so a late response never reopens it.
Does it handle Japanese, Chinese or Korean input?
Yes. While an IME composition is in progress it waits, and searches once the composition ends.
How do I change how it looks?
Override the --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.
Should I close it or destroy it?
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.
How big is the bundle?
The browser IIFE build is approximately 12 KiB gzipped, plus 0.8 KiB gzipped for the optional stylesheet. There are zero runtime dependencies.
Search your users can rely on

Make every search feel instant.

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