Awesomplete: a zero-dependency autocomplete widget you drop into a page
Ultra lightweight, usable, beautiful autocomplete with zero dependencies.
At a glance
- What is it?
- Awesomplete is a single JavaScript file and a stylesheet that turn an input into an autocomplete field, with no framework and no dependencies. package.json declares version 1.1.7 while the last GitHub release is v1.1.5 from 2019, so the release list does not show the newest version.
- Who is it for?
- Reach for Awesomplete when you want autocomplete on a plain HTML form and do not want a framework or a dependency tree: it is one script and one stylesheet, and an input with class="awesomplete" and a data-list attribute is enough to start.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 113 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- nudeui/awesomplete6,966 ★ · -3
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| nudeui/awesomplete | 7k | 7k |
-3 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What Awesomplete is for, and who ends up using it
Awesomplete solves a narrow problem: an input field where the user should pick from a known set of strings, with a popup of matches and keyboard selection, without pulling in a UI framework. The README describes it as an "ultra lightweight, customizable, simple autocomplete widget with zero dependencies, built with modern standards for modern browsers." The audience that follows from that description is whoever maintains server-rendered HTML, a static site, or a small script tag on a page where a build step is unwelcome. The repository ships awesomplete.js, awesomplete.min.js, awesomplete.css, awesomplete.base.css and awesomplete.theme.css at the top level, so the artifact you deploy is a script and a stylesheet rather than a bundle. It is a poor fit for a team that expects suggestions to come from a search endpoint as the user types; nothing in the README describes a remote data source.
The mechanism: an input, a list source, and a generated popup
The data flow is short enough to hold in your head. You give the widget a source of suggestions through the list option or the data-list attribute, and the README says that value can be an array of strings, an HTML element, a CSS selector (with the explicit caveat "no groups, i.e. no commas"), or a string containing a comma-separated list of items. When the user types past minChars, the widget filters that source and renders matches into a generated list, capped at maxItems. The listLabel option supplies the aria-label on that generated list, which defaults to Results List. autoFirst, off by default, decides whether the first match is preselected. Because the source can be a selector, the suggestions can live in ordinary markup in the page: the README shows both a datalist element and a plain ul with li children being used as the list. That is the whole architecture. The README documents no request layer, which is also why long lists are a design problem rather than a tuning problem.
Installing Awesomplete and getting a first input working
The README lists two ways to obtain the files. The first is a CDN entry on cdnjs, given as a URL rather than a command. The second is a package manager, and both commands are quoted in the README.
yarn add awesompletenpm install awesomplete --saveAfter that, the README says you need to include awesomplete.css and awesomplete.js in the page with the usual tags. Note the async attribute on the script in the README's own snippet.
<link rel="stylesheet" href="awesomplete.css" />
<script src="awesomplete.js" async></script>The shortest working widget is one input. Adding class="awesomplete" is what tells the library to process it automatically, and the README notes you can still pass options through HTML attributes.
<input class="awesomplete"
data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" />Load the page and type two characters into the field. The default minChars is 2, so that is when the popup appears, and it will show up to maxItems suggestions, which defaults to 10. If you would rather not put the values in an attribute, the README's datalist form keeps a native fallback when the script does not load, and the ul form avoids IDs entirely because any selector works in data-list. Beyond that, the README points at the API documentation on the project site for the full set of properties.
Where Awesomplete stops being the right tool
The list option is the constraint that decides most adoption questions. Every form the README documents is local: an array, an element, a selector, or a comma-separated string. If your suggestions come from a database query or a search service, you are writing that integration yourself, and the README does not describe a hook for it. The second constraint is scale. maxItems caps what is displayed, not what you ship, so a list of ten thousand entries means ten thousand strings in the page or in a script before the user types anything. The third is release cadence. The newest release listed in the repository is v1.1.5, dated 2019-08-21, while package.json carries version 1.1.7, so the package.json version and the newest release do not line up. The last push to the repository was on 2026-07-25, and the repository is not archived, but a gap of more than seven years since the last release is the number to weigh if you depend on fixes arriving. Finally, the test toolchain in package.json pins karma at ^0.13.19 and jasmine-core at ^2.4.1, which is old enough that running npm test on a current Node install is its own project.
Awesomplete against a framework component or a full combobox library
The realistic alternative is not another standalone autocomplete script; it is the autocomplete component that ships with whatever renders your UI, or a combobox library built around a framework's data flow. The difference is where state lives. Awesomplete reads a list you already have in the document or in a variable and writes a popup next to the input; a framework component owns the input value, the open state and the filtered results in its own render cycle, and it usually expects suggestions to arrive as props or from a store. If your page is plain HTML, adopting a framework component means adopting the framework. If your page is already a React or Vue application, Awesomplete is a foreign object in that tree: the README documents no component wrapper, and the instantiation path it describes is a class on an input or a few lines of JavaScript. The trade runs the other way too. A framework component will not work if your script tag is the only build step you have, and the README documents no way to bind Awesomplete to a state store.
Maintenance, upgrades and the MIT licence
The repository is not archived and the last push was on 2026-07-25, so there is activity, but the release history tells a different story: v1.1.3 on 2018-09-19, v1.1.4 on 2019-01-07, v1.1.5 on 2019-08-21, and nothing newer in the release list. The package.json version of 1.1.7 sits above all of them, which means you should read the changelog and the published package rather than assume the release list is current. Upgrade cost is low in one direction and awkward in another. The runtime surface is a script and a stylesheet with no dependencies, so replacing it later is mostly a matter of removing two tags and a class. The maintenance surface is the devDependencies: gulp 3, karma 0.13 and jasmine-core 2.4 are old, and the release script is release-it ^17.6.0, so anyone who wants to build or test the project itself is dealing with a mixed-age toolchain. The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT permits commercial use and modification, but the file is the authority, and this is not legal advice.
Editorial conclusion
Reach for Awesomplete when you want autocomplete on a plain HTML form and do not want a framework or a dependency tree: it is one script and one stylesheet, and an input with class="awesomplete" and a data-list attribute is enough to start. Skip it if you need remote suggestion fetching or a component that fits a React or Vue render model; the README documents none of those, and the documented list option takes an array, an element, a selector or a comma-separated string, not a URL. Before adopting it, check which version your package manager actually resolves, since package.json says 1.1.7 and the newest release listed in the repository is v1.1.5 from 2019-08-21, and confirm that the suggestion list is short enough to ship inside the page.
Frequently asked questions
What is the use of autocomplete?
In Awesomplete's case, it shows a popup of matching suggestions as the user types into an input, so they can pick from a known set of strings instead of typing one from memory. The widget filters the list you supply and displays up to maxItems matches once the input passes minChars.
How can I implement autocomplete in JavaScript?
Include awesomplete.css and awesomplete.js on the page, then add class="awesomplete" to an input along with a data-list attribute holding your suggestions. The library processes inputs with that class automatically, or you can instantiate it in JavaScript for more customization.
How do I install Awesomplete?
The README gives two routes: a cdnjs entry, or a package manager, with yarn add awesomplete and npm install awesomplete --save quoted as the commands. After that you include awesomplete.css and awesomplete.js in the page.
Which version of Awesomplete will I get?
package.json in the repository declares version 1.1.7, while the newest release listed in the repository is v1.1.5 from 2019-08-21. The README does not resolve that difference, so check the published package and the changelog before pinning a version.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nudeui-awesomplete)Star history chart for your README
[](https://hysenlabs.com/projects/nudeui-awesomplete)Was this useful?