# Algolia Autocomplete: A Headless Combobox Library for Custom Search UIs

> Algolia's Autocomplete is a TypeScript library for building accessible autocomplete experiences on top of any data source, not only Algolia indexes. It ships as a monorepo of packages, and its main trade-off is that you own the rendering.

**algolia/autocomplete** — 🔮 Fast and full-featured autocomplete library

- Repository: https://github.com/algolia/autocomplete
- Website: https://alg.li/autocomplete
- Stars: 5,264 · Forks: 340
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/algolia-autocomplete

## The problem Autocomplete solves, and who it is for

Building a combobox from scratch is mostly accessibility work. You need the right ARIA attributes, keyboard handling for arrow keys, Enter and Escape, focus management, and a panel that behaves correctly when results arrive asynchronously. Algolia Autocomplete takes that layer and leaves the markup to you. The README describes it as "A JavaScript library that lets you quickly build autocomplete experiences", and the two required parameters are container and getSources. Everything else is optional configuration.

The intended audience is front-end engineers who already have a design system and do not want a widget that fights it. The library creates an input and provides the interactivity and accessibility attributes, but the README states you are in full control of the DOM elements to output. If your team has no opinion about markup, this gives you less than a packaged component would. If your team has a strong opinion, it gives you more.

## Sources, state and the renderer: how the data flow actually works

The central concept is the source. A source is a function that returns items for the current query, and the README is explicit that a source can be anything: a static list of search terms, results from an external API such as an Algolia index, or recent searches. There is no requirement that the data come from Algolia.

Around the sources sits a state object. The documentation points readers to Core Concepts pages for Sources and State, which is where the query, the active item and the collections of results live. The autocomplete-js package bundles a renderer built on a Virtual DOM, and the README notes it works with any Virtual DOM solution (JavaScript, Preact, React, Vue). If you want to supply your own rendering pipeline instead, autocomplete-core exposes the primitives and the documentation has a guide on creating a renderer from scratch. That split is the architecture in one sentence: core holds state and interaction, autocomplete-js adds a default renderer, plugins extend behaviour.

## Installing autocomplete-js and rendering a first panel

The recommended entry point is the autocomplete-js package, which the README says includes everything needed to render a JavaScript autocomplete experience. Install it with your package manager:

```bash
yarn add @algolia/autocomplete-js
# or
npm install @algolia/autocomplete-js
```

If you do not use a package manager, the README gives a script tag pointing at jsDelivr, after which the function is available on the window under the package name:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-js"></script>
<script>
  const { autocomplete } = window['@algolia/autocomplete-js'];
</script>
```

Next, add a container to your markup. The README warns to provide a container such as a div, not an input, because Autocomplete generates a fully accessible search box itself:

```html
<div id="autocomplete"></div>
```

Then call autocomplete with the container and your sources. The container accepts a CSS selector or an Element:

```js
import { autocomplete } from '@algolia/autocomplete-js';

autocomplete({
  container: '#autocomplete',
  // ...
});
```

At this point you should see an input rendered inside the div. With no getSources configured you get no results, which is expected: the README treats container and getSources as the two required parameters. For a complete working configuration, the repository has an examples/playground directory and a CodeSandbox link in the README where the basic implementation can be forked.

## Where the headless approach costs you

The same design decision that makes the library flexible makes it incomplete. There is no default result markup to fall back on, so a team that wants a search box by Friday will spend that time writing item templates and styling the panel. The examples directory shows how much ground that covers: starter, html-templates, panel-placement, preview-panel-in-modal, tags-in-searchbox, and a dozen query-suggestion variants. Each is a separate pattern you assemble yourself.

A second constraint is the client-side renderer. The library injects into a container through a Virtual DOM, so it assumes JavaScript runs in the browser. If your pages are server-rendered and you avoid client-side rendering, this is the wrong tool, and a native datalist element or a server-rendered suggestion list will fit better.

The rendering model also means your bundle grows with your choices. autocomplete-js pulls in a renderer; autocomplete-core does not. That trade is available, but it is a decision you have to make deliberately rather than a default you inherit.

## Plugins: recent searches, query suggestions and insights

The monorepo ships several packages beyond the two core ones. autocomplete-plugin-recent-searches adds recent searches to the experience. autocomplete-plugin-query-suggestions adds query suggestions. autocomplete-plugin-algolia-insights wires up Algolia Insights, which is the one plugin that is meaningful only if you are an Algolia customer. autocomplete-plugin-redirect-url handles redirect behaviour.

The example list reflects how these combine in practice: query-suggestions-with-recent-searches, query-suggestions-with-categories, query-suggestions-with-hits, and a longer variant covering recent searches and categories together. If your requirements match one of those combinations, you are following a path the maintainers already exercise. If your requirement is a source shape that none of the examples covers, you are writing the source yourself, which the README presents as normal usage rather than an escape hatch.

## Alternatives and the real difference in approach

The closest comparison inside the same ecosystem is InstantSearch. The repository includes examples/instantsearch and examples/react-instantsearch, and the distinction is scope: InstantSearch is a full search UI toolkit with its own widgets and its own state management, while Autocomplete is a combobox that can be dropped into a page that has no other search UI. If you need facets, pagination and a results page, InstantSearch covers more of that surface. If you need a search box that suggests and then hands off, Autocomplete is the smaller dependency.

Outside the Algolia ecosystem, the honest comparison is a general-purpose combobox component from whatever UI framework you already use. Those components typically ship styled, opinionated markup and a fixed data interface. Autocomplete inverts both: unstyled output you write, and sources you define. The difference is not quality, it is where the work sits. Choosing a styled component moves the work into theming and fighting defaults. Choosing Autocomplete moves the work into writing item renderers and sources.

## Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-22. Releases are frequent and small: v1.19.11 on 2026-09-22, v1.19.10 on 2026-09-07, and v1.19.9 on 2026-06-23. The version numbers staying inside 1.19.x suggests patch-level churn rather than a migration-heavy cadence, though the repository's default branch is named next, which is worth knowing when you read source links or file paths against a tagged release.

The licence is MIT, which is permissive and places few obligations on how you redistribute the library. That is a statement about the licence text, not legal advice; if your organisation has a policy on third-party dependencies, run it through that process.

Upgrade cost is dominated by your own code, not the library's. Because you own the rendering and the sources, a library upgrade does not rewrite your markup, but it can change the state shape your sources and renderers read. The monorepo runs its own test suite through jest and a separate test:versions script, and the CHANGELOG.md at the repository root is where release notes land.

## Conclusion

Adopt it if you need a headless combobox with real accessibility attributes and you are willing to write the rendering yourself, or if you are already on Algolia indexes and want the query suggestions and insights plugins. Skip it if you expect a styled, batteries-included widget, or if your UI is fully server-rendered and you cannot ship a client-side renderer. Before committing, check that your container is a div and not an input, confirm which Virtual DOM solution your stack already has, and read the API reference for the parameters your design depends on.

## FAQ

### What is Algolia Autocomplete?

It is a JavaScript library for building autocomplete experiences, published as a set of packages on npm. The README describes it as a library where you supply a container and a getSources function, and it creates the input plus the interactivity and accessibility attributes.

### How do I install Algolia Autocomplete?

The README recommends the autocomplete-js package, installed with yarn add @algolia/autocomplete-js or npm install @algolia/autocomplete-js. Without a package manager, a script tag pointing at the jsDelivr build exposes autocomplete on the window.

### Can I use Algolia Autocomplete without an Algolia index?

Yes. The README states that sources can hold whatever you want, including a static set of search terms, results from an external source, or recent searches. Only the autocomplete-plugin-algolia-insights package is tied to Algolia's own service.

### Should the container be an input element?

No. The README says to provide a container such as a div, not an input, because Autocomplete generates a fully accessible search box itself. The container can be a CSS selector or an Element.

### How do I use autocomplete in HTML without a build step?

The README shows loading the package from jsDelivr with a script element, then reading autocomplete from window['@algolia/autocomplete-js']. You still need a container element in the markup and a getSources configuration for results to appear.

## Sources

- [algolia/autocomplete on GitHub](https://github.com/algolia/autocomplete)
- [License: MIT](https://github.com/algolia/autocomplete/blob/next/LICENSE)
- [Project website](https://alg.li/autocomplete)
- [README](https://github.com/algolia/autocomplete/blob/next/README.md)
- [Releases](https://github.com/algolia/autocomplete/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/algolia-autocomplete