Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Awesomplete
✓ <!-- In HTML, after awesomplete.js is loaded -->
<script>
const input = document.querySelector('.awesomplete-input');
const awesomplete = new Awesomplete(input, {
list: ['Apple', 'Banana', 'Cherry']
});
</script>
Awesomplete is primarily accessed as a global object after including its script via a <script> tag in HTML. This is the intended and most common usage pattern.
Awesomplete
✓ const Awesomplete = require('awesomplete');
// Then use `new Awesomplete(...)`
✗ import Awesomplete from 'awesomplete';
While `awesomplete.js` is set as the `main` entry in `package.json`, enabling CommonJS `require`, the library does not provide native ES module exports. Attempting to use `import` without bundler configuration will likely fail.
CSS and JS
✓ <link rel="stylesheet" href="path/to/awesomplete.css" />
<script src="path/to/awesomplete.js" async></script>
✗ import 'awesomplete/awesomplete.css'; // May not work depending on bundler config
import 'awesomplete/awesomplete.js';
For basic setup, direct HTML inclusion of the CSS and JS files is the most reliable method, especially in non-bundler environments. Relying on module imports for CSS/JS requires appropriate bundler loaders/plugins.
This quickstart demonstrates both declarative HTML-based setup with `data-list` and programmatic JavaScript instantiation for an autocomplete input, showing how to link a custom list of suggestions and configure basic options like `minChars` and `autoFirst`.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Awesomplete Quickstart</title>
<link rel="stylesheet" href="https://unpkg.com/awesomplete@1.1.7/awesomplete.css" />
</head>
<body>
<h1>Awesome Autocomplete</h1>
<label for="my-input">Select a Programming Language:</label>
<input id="my-input" class="awesomplete" data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" />
<h2>Programmatic Example</h2>
<label for="custom-input">Choose a Fruit:</label>
<input id="custom-input" />
<script src="https://unpkg.com/awesomplete@1.1.7/awesomplete.js" async></script>
<script>
window.addEventListener('load', () => {
// Example 1: Declarative setup using HTML attributes (data-list)
// The input with class="awesomplete" and data-list is automatically processed.
// Example 2: Programmatic setup for more control
const inputCustom = document.getElementById('custom-input');
new Awesomplete(inputCustom, {
list: [
'Apple', 'Apricot', 'Avocado', 'Banana', 'Blackberry', 'Blueberry',
'Cherry', 'Coconut', 'Cranberry', 'Date', 'Dragonfruit', 'Durian',
'Elderberry', 'Fig', 'Grape', 'Guava', 'Kiwi', 'Lemon', 'Lime',
'Mango', 'Melon', 'Nectarine', 'Orange', 'Papaya', 'Passion Fruit',
'Peach', 'Pear', 'Pineapple', 'Plum', 'Pomegranate', 'Raspberry',
'Strawberry', 'Watermelon'
],
minChars: 1, // Show suggestions after 1 character
autoFirst: true // Highlight the first item automatically
});
// Event listener example (optional)
inputCustom.addEventListener('awesomplete-selectcomplete', (e) => {
console.log('Selected:', e.text.value);
});
});
</script>
</body>
</html>
Debug
Known issues
breakingA breaking change was introduced in `v1.1.3` or `v1.1.4` (exact version unclear from provided data), but was subsequently reverted in `v1.1.4`.fixEnsure you are using `v1.1.4` or later to avoid the reverted breaking change. The project documentation does not specify the exact nature of the break.
affects: v1.1.3 (briefly)
gotchaAwesomplete is largely unmaintained. The last significant update was in 2018 (version 1.1.7). This means it may not receive updates for new browser features, security vulnerabilities, or bug fixes. Community support is also limited.fixFor new projects, consider more actively maintained alternatives. If used in existing projects, be aware of potential long-term compatibility or security issues. Thoroughly test with modern browsers and review for any known vulnerabilities.
affects: >=1.1.7
gotchaThe library primarily exposes `Awesomplete` as a global variable. In environments using module bundlers (Webpack, Rollup, Parcel), attempting to `import Awesomplete from 'awesomplete'` will not work directly as the package lacks native ES module exports. It only defines a `main` entry for CommonJS.fixFor CommonJS, use `const Awesomplete = require('awesomplete');`. For ES modules in a bundler, you might need to configure your bundler to handle CommonJS modules or continue to load it as a global script and rely on `window.Awesomplete`. affects: All versions
gotchaAwesomplete does not officially ship with TypeScript definitions. While `@types/awesomplete` is available on DefinitelyTyped, it is also somewhat outdated (last updated ~2 years ago) and may not perfectly reflect the runtime API, especially for edge cases or specific event types.fixInstall `@types/awesomplete` separately (`npm install --save-dev @types/awesomplete`). Be prepared to write custom type declarations or cast types (`as any`) for parts of the API not fully covered or accurately reflected.
affects: All versions
gotchaWhen dynamically manipulating the suggestion list while the Awesomplete popup is open, changes may not immediately reflect. The `evaluate()` method must be called to refresh the displayed suggestions.fixAfter updating the `list` property of an Awesomplete instance (e.g., `awesomplete.list = newList;`), explicitly call `awesomplete.evaluate();` to force a re-evaluation and redraw of the suggestion list.
affects: All versions
Errors
Common errors & fixes
ReferenceError: Awesomplete is not defined
The `awesomplete.js` script was not loaded or executed before attempting to use the `Awesomplete` global object, or it was incorrectly imported in a module environment.
fixEnsure `awesomplete.js` is included via a `<script>` tag in your HTML *before* any inline scripts that use it. If using `npm`/`yarn`, ensure your bundler correctly processes and exposes it globally, or explicitly `require('awesomplete')` in a CommonJS context. Autocomplete suggestions do not appear when typing.
The `minChars` option is set too high (default is 2), or the `list` property (either `data-list` HTML attribute or JavaScript `list` option) is empty, incorrectly formatted, or points to a non-existent element/selector.
fixCheck the `minChars` option and ensure it's set to an appropriate number (e.g., `1`). Verify that the `data-list` attribute or the `list` JavaScript option contains valid suggestions (e.g., a comma-separated string, array of strings, or a valid CSS selector pointing to a list element).
Awesomplete interferes with other scripts or styles.
The library creates and manages DOM elements and attaches event listeners, which can sometimes conflict with other client-side libraries, especially given its unmaintained status.
fixEnsure that Awesomplete's CSS and JS are loaded in a way that minimizes global impact (e.g., specific selectors, scoped styles). If conflicts occur, investigate the `Awesomplete.destroy()` method to clean up instances, or consider isolating its usage to specific parts of your application.
Audit
Dependencies
No dependency data recorded yet.