# autoComplete.js: A Zero-Dependency Autocomplete Library for Plain JavaScript

> autoComplete.js is a vanilla JavaScript autocomplete library with no runtime dependencies and a roughly 3.7 KB gzipped bundle. It suits projects that want a suggestion dropdown without React or jQuery, and it is a poor fit when you need a full combobox with grouped options or virtual scrolling.

**TarekRaafat/autoComplete.js** — Simple autocomplete pure vanilla Javascript library.

- Repository: https://github.com/TarekRaafat/autoComplete.js
- Website: https://tarekraafat.github.io/autoComplete.js
- Stars: 4,033 · Forks: 245
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/tarekraafat-autocomplete-js

## The gap autoComplete.js fills: suggestions without a framework

Most autocomplete widgets assume you have already chosen a stack. Downshift and react-select are React-only. Select2 requires jQuery. Algolia Autocomplete ships a Preact core. If your page is server-rendered HTML with a script tag, those options mean adding a runtime you did not otherwise need. autoComplete.js takes the opposite position: the README describes it as "Simple autocomplete pure vanilla Javascript library" with zero dependencies, and package.json lists no runtime dependencies at all, only devDependencies for Babel, Rollup and Terser. The README's comparison table puts the gzipped size at roughly 3.7 KB, against roughly 8 KB for Downshift and roughly 25 KB for Algolia Autocomplete. It is aimed at developers who want the dropdown behaviour and nothing else: no virtual DOM, no state container, no CSS framework. The README also notes it works on input, textarea and contentEditable elements, which matters if your search field is not a plain input. The trade-off is that you own more of the integration: rendering, styling and the glue to your data source are yours to write. That is not a defect, but it is the reason the comparison table's size column is not the whole story. A 3.7 KB library that needs 200 lines of adapter code is not obviously cheaper than a 16 KB library that needs none, and the honest way to decide is to count the features you would otherwise have to build.

## How the search engine and lifecycle events work

The library is configured through a single options object passed to the constructor. Two pieces of that object do most of the work: a data source and a set of lifecycle hooks. The README lists two search modes and diacritics support, debounce support, lifecycle events and a plugin API as features, so the flow is roughly: the user types, the debounce window closes, the library queries the configured source, the search mode filters or ranks the results, and the results are handed to the render hook. The repository layout backs this up: src/ holds the source, dist/ holds the built bundles, and rollup.config.js drives the build. Because the source is plain JavaScript with no framework layer, the lifecycle events are the extension point rather than a component tree. That is a real design choice with consequences. You get hooks to run your own code at defined moments, but you do not get a declarative component that re-renders when your data changes. If your suggestion list is driven by remote results, you are responsible for fetching them and passing them to the library at the right moment. The plugin API exists for the same reason: rather than growing the core, the project expects behaviour to be attached from outside. The two search modes are worth reading about in the docs before you pick one, because the difference between them changes how results are ranked, and the README does not spell that out in the text above; it defers to the documentation site and to the llms.txt and llms-full.txt files shipped in the repository root.

## Installing autoComplete.js from npm or the CDN

There are two documented paths. The package manager route installs from npm under the scoped name @tarekraafat/autocomplete.js:

```shell
npm i @tarekraafat/autocomplete.js
```

Yarn works the same way, per the README:

```shell
yarn add @tarekraafat/autocomplete.js
```

The CDN route needs two files, the script and the stylesheet. The README pins both to version 10.2.10, which is worth copying rather than using a floating tag:

```html
<script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.10/dist/autoComplete.min.js"></script>
```

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.10/dist/css/autoComplete.min.css">
```

After the script loads, the global is available and you construct an instance against a selector. The README does not print a full constructor example in the text above, but it points to the docs site for usage and configuration details, and the repository ships llms.txt and llms-full.txt alongside the docs directory. If you want the exact option names for the data source, search modes, debounce and the render hook, read those files rather than guessing; the package.json main field points at dist/autoComplete.js and the browser field at dist/autoComplete.min.js, so bundler and script-tag consumers resolve to different files. Your first real check is that a dropdown appears when you type, and that the styling comes from the CSS file rather than from your own stylesheet. If the dropdown renders unstyled, you have loaded the script but not the CSS, which is the most common first-run mistake with this library.

## Where autoComplete.js is the wrong choice

The library is a suggestion engine, not a full combobox. The README claims WAI-ARIA compliance, but it does not describe grouped options, virtual scrolling for very large lists, or a multi-select mode. If your product needs any of those, you will be building them on top of the lifecycle hooks, and at that point the size advantage over Tom Select or Choices.js stops being the deciding factor. A second limitation is the rendering boundary. Because the library is framework-agnostic, it cannot know about your component state; when your data source changes, you re-supply it. In a React or Vue application with derived state, that means writing an adapter, and the adapter is where bugs live. Third, the README does not document rollback behaviour or a migration path between major versions. The release history shows a gap: v10.2.8 landed on 2024-10-16, v10.2.9 on 2024-10-22, and v10.2.10 on 2026-04-12, which is a long quiet stretch for a library with a live issue tracker. That does not make it abandoned, and the last push to the repository was on 2026-06-30, but it does mean you should read CHANGELOG.md and ROADMAP.md before you assume a fix is coming for anything you hit. Finally, if your autocomplete is really a search product, with ranking, synonyms and analytics, a hosted engine will do more than this library ever intends to. The project's own support notes point technical questions to Stack Overflow under the autoCompletejs tag and general questions to GitHub Discussions, which tells you where maintainer attention is expected to land.

## Tom Select and Downshift as alternatives, and how they differ

Tom Select is the closest comparison in the README's own table: no framework required, roughly 16 KB gzipped, one dependency, and described as drop-in. The difference in approach is scope. Tom Select is a select replacement, so it brings multi-select, tagging, option groups and remote loading as built-in behaviour. autoComplete.js gives you a smaller core and a plugin API, and expects you to assemble the rest. If your requirement is a form control that behaves like an enhanced select, Tom Select saves you the assembly. If your requirement is a single suggestion dropdown on a search field, autoComplete.js is the smaller thing to ship. Downshift sits on the other axis: roughly 8 KB gzipped, five dependencies, React only. It gives you the state machine and render props for a combobox and leaves markup and styling to you, which is a similar philosophy to autoComplete.js but bound to React. Choosing between them is less about size and more about whether your application already has React in the bundle. If it does, Downshift's integration is more natural. If it does not, adding React to get a dropdown is the wrong trade. Choices.js, listed at roughly 20 KB with no dependencies, is a third option if you want a styled select-like control without a framework; the README's table places it between Tom Select and Algolia Autocomplete on both size and scope.

## Maintenance, versioning and the Apache-2.0 licence

The package version in package.json is 10.2.10, matching the most recent release on 2026-04-12. The last push to the repository was on 2026-06-30, so there has been activity after the release, though the README does not say what it contains; CHANGELOG.md is the place to look. Upgrade cost is low in principle because there are no runtime dependencies to reconcile, but the project's own release cadence is uneven: v10.2.8 and v10.2.9 arrived six days apart in October 2024, then nothing until April 2026. Pin an exact version in your lockfile rather than relying on a CDN tag that could move. The package.json files array publishes only dist and src, so anything you import from a path outside those two directories will not exist in the installed package. On licensing, the project is released under Apache-2.0, which is a permissive licence that includes an explicit patent grant and requires you to preserve notices and state changes. That is generally friendlier for corporate use than a copyleft licence, but it is not legal advice; if you are redistributing the library inside a product, have your own counsel read the LICENSE file. The README also lists downstream users including IBM Carbon, The Guardian, Snapcraft, Weblate, Blockscout and Eclipse Ditto, which tells you the library has survived contact with large codebases, though it says nothing about whether those projects still depend on it today.

## Conclusion

Adopt autoComplete.js when you need a small, dependency-free suggestion dropdown on an input, textarea or contentEditable element and you are willing to write your own result rendering and accessibility wiring. Skip it if you need a full combobox with grouped options, virtual scrolling or framework-bound state, and look at Tom Select or Downshift instead. Before committing, verify two things in your own environment: that the WAI-ARIA behaviour holds up in the browsers you support, and that the 10.2.10 dist files on your chosen CDN match the version in your lockfile. The last push to the repository was on 2026-06-30, and the most recent release is v10.2.10 from 2026-04-12, so read CHANGELOG.md and ROADMAP.md before pinning a version.

## FAQ

### How do I install autoComplete.js from npm?

Run npm i @tarekraafat/autocomplete.js, or yarn add @tarekraafat/autocomplete.js. The package is published under the scoped name, not as plain autoComplete.js.

### Can I load autoComplete.js from a CDN instead of npm?

Yes. The README gives a jsDelivr script tag and a matching stylesheet link, both pinned to version 10.2.10. You need both files, since the dropdown styling comes from the CSS bundle.

### Does autoComplete.js work with React?

The library itself is framework-agnostic vanilla JavaScript, and the README does not document a React binding. Using it in a React app means writing your own wrapper around the constructor and lifecycle events.

### What is the use of autocomplete?

In this project, autocomplete is the suggestion dropdown that appears as a user types into an input, textarea or contentEditable element. autoComplete.js provides the search engine, lifecycle events and rendering hooks for that dropdown.

## Sources

- [License: Apache-2.0](https://github.com/TarekRaafat/autoComplete.js/blob/master/LICENSE)
- [Project website](https://tarekraafat.github.io/autoComplete.js)
- [README](https://github.com/TarekRaafat/autoComplete.js/blob/master/README.md)
- [Releases](https://github.com/TarekRaafat/autoComplete.js/releases)
- [TarekRaafat/autoComplete.js on GitHub](https://github.com/TarekRaafat/autoComplete.js)

---

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