Awesomplete

Common errors

• ReferenceError: Awesomplete is not defined

  cause 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.
  fix Ensure `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.

  cause 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.
  fix Check 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.

  cause 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.
  fix Ensure 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.

Warnings

• breaking A 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`.
  Fix: Ensure 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.
• gotcha Awesomplete 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.
  Fix: For 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.
• gotcha The 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.
  Fix: For 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`.
• gotcha Awesomplete 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.
  Fix: Install `@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.
• gotcha When 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.
  Fix: After 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.

Install

• npm install awesomplete npm
• yarn add awesomplete yarn
• pnpm add awesomplete pnpm

Imports

• 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
  wrong:

  import Awesomplete from 'awesomplete';

  correct:

  const Awesomplete = require('awesomplete');
  // Then use `new 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
  wrong:

  import 'awesomplete/awesomplete.css'; // May not work depending on bundler config
  import 'awesomplete/awesomplete.js';

  correct:

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

  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.

Quickstart

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>