Awesomplete: lightweight JavaScript autocomplete without dependencies

Awesomplete provides autocomplete with the native datalist fallback

Awesomplete is an ultra lightweight autocomplete widget for HTML input elements. It is customizable, simple, and built with modern standards for modern browsers. The key design is zero runtime dependencies; Awesomplete relies only on vanilla JavaScript APIs supported natively in modern browsers. Version 1.1.7 ships at kilobytes, not megabytes, making it suitable for bandwidth-constrained environments or pages that must load quickly.

Unlike larger frameworks, Awesomplete degrades gracefully. You can structure your HTML using the native `<datalist>` element, which provides autocomplete in browsers that support it even if the JavaScript does not load. Awesomplete enhances this native behavior with styling and additional interactivity. The library comes with multiple CSS files: awesomplete.base.css contains the structural styles, awesomplete.css adds default theming, and awesomplete.theme.css provides an alternative visual style. You can use the base stylesheet alone and add your own theme, or replace the default theme entirely. Source maps are included for debugging, and minified versions are available for production.

Installing Awesomplete via npm or CDN

Install Awesomplete from npm:

npm install awesomplete --save

Alternatively, use yarn:

yarn add awesomplete

Alternatively, include it from a CDN like cdnjs.com. Using CDN, add these tags to your HTML:

<link rel="stylesheet" href="awesomplete.css" />
<script src="awesomplete.js" async></script>

Version 1.1.7 is the current release. Installation from npm or CDN gives you access to both the minified (`awesomplete.min.js`) and source (`awesomplete.js`) versions.

Adding autocomplete to an input with data-list attribute

The simplest way to add autocomplete is to add the `awesomplete` class to an input and specify suggestions with the `data-list` attribute:

<input class="awesomplete"
       data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" />

The class `awesomplete` automatically enables the widget with default options. The `data-list` attribute accepts a comma-separated string of suggestions.

For a fallback experience in case the script doesn't load, use the HTML5 `<datalist>` element:

<input class="awesomplete" list="mylist" />
<datalist id="mylist">
	<option>Ada</option>
	<option>Java</option>
	<option>JavaScript</option>
</datalist>

Browsers with native datalist support will show autocomplete even without the JavaScript. You can also reference a list using a CSS selector:

Configuring suggestion behavior with minChars, maxItems and autoFirst

Awesomplete supports customization through HTML attributes or JavaScript properties. Key configurable properties are:

- `minChars` (default 2): Minimum characters typed before showing suggestions. Set this higher to reduce noise on short inputs, lower for very specific lists - `maxItems` (default 10): Maximum number of suggestions to display in the dropdown - `autoFirst` (default false): Whether to automatically select and highlight the first suggestion as the user types. When enabled, pressing Enter without moving through the list selects the first match - `listLabel` (default "Results List"): ARIA label for the suggestion list, important for accessibility and screen readers. Custom labels help assistive technology describe the autocomplete context to users

The `list` property defines where suggestions come from. It accepts an array of strings, an HTML element, a CSS selector (without commas), or a comma-separated string.

Specify these options as HTML attributes (with `data-` prefix like `data-minchars="1"`) or pass them as an object when instantiating in JavaScript. You can instantiate Awesomplete with JavaScript code for more customization beyond HTML attributes, allowing dynamic initialization, event handlers, and filtering logic. This is useful when suggestions are computed at runtime or filtered based on other form state.

Multiple ways to provide suggestion lists from arrays, selectors or strings

Awesomplete is flexible about suggestion sources. You can provide suggestions in three ways:

1. As a simple comma-separated list in the `data-list` attribute 2. As a native HTML5 `<datalist>` element referenced by `list` attribute 3. As a `<ul>` or other HTML element referenced by a CSS selector in `data-list`

Using a `<ul>` element:

<input class="awesomplete" data-list="#mylist" />
<ul id="mylist">
	<li>Ada</li>
	<li>Java</li>
	<li>JavaScript</li>
</ul>

This approach works with any element; any CSS selector works in data-list (except grouped selectors with commas). This flexibility means you can build suggestion lists from existing markup without duplicating data or writing JavaScript.

When instantiating Awesomplete via JavaScript rather than HTML attributes, the `list` property accepts an array of strings, an HTML element object, or a CSS selector string. Providing an array gives you the most control, allowing you to populate suggestions dynamically from API calls or computed data.

Maintenance status and API documentation

The last push to Awesomplete was on 2026-07-25. The most recent releases are v1.1.5 from 2019-08-21, v1.1.4 from 2019-01-07, and v1.1.3 from 2018-09-19. These dates indicate the project receives occasional maintenance updates but is not under active feature development. The repository is not archived, so fixes and patches do arrive, though infrequently.

Awesomplete is licensed under the MIT license. The official site is at leaverou.github.io/awesomplete, which includes documentation for the API and other topics. The project was created by Lea Verou with contributions from other developers. The repository follows standard open source practices with issue tracking on GitHub and contribution guidelines in CONTRIBUTING.md. The test suite runs via Karma with jasmine-core as the test framework, and devDependencies include gulp for building. The minimal size and zero-dependency design have made Awesomplete a reference implementation for lightweight autocomplete, used in educational settings and as a benchmark for evaluating larger autocomplete libraries. The repository structure includes a Makefile and build system for generating release artifacts.

Editorial conclusion

Use Awesomplete if you need autocomplete on a website and want minimal JavaScript overhead. Skip it if you need advanced features like grouping, keyboard navigation hooks, or dynamic data fetching. Start by installing from npm, including the CSS and JavaScript files in your page, and adding the awesomplete class to an input element.

Frequently asked questions

Official sources

1. License: MIT
2. nudeui/awesomplete on GitHub
3. Project website
4. README
5. Releases