JavaScript AutoComplete Library

1.0.5 · abandoned · verified Sun Apr 19

JavaScript-autoComplete is an extremely lightweight and powerful vanilla JavaScript completion suggester. Developed by Pixabay.com, it provides flexible data sourcing, smart caching, and callback functionalities with no external dependencies. The library is very small, weighing in at less than 2.4 kB gzipped. It was last updated in 2016, with its current stable version being 1.0.5. Given its age and lack of recent development, it operates on a very slow release cadence and is primarily intended for environments where a minimal, standalone JavaScript solution is preferred over modern, framework-integrated alternatives. Key differentiators include its zero-dependency nature and extreme lightness, making it suitable for legacy projects or very simple, performance-critical contexts where a full-featured library would be overkill.

Common errors

```
ReferenceError: AutoComplete is not defined
```
cause The `auto-complete.min.js` script was not loaded or executed before `new AutoComplete()` was called. This often happens if the script tag is placed incorrectly or if there's a network issue preventing the script from loading.

fix Ensure the `<script src="..."></script>` tag for `auto-complete.min.js` is placed in the HTML document before any script that attempts to use the `AutoComplete` constructor, typically at the end of the `<body>`. Verify the script path is correct and accessible.
```
Uncaught TypeError: Cannot read properties of null (reading 'style')
```
cause This error can occur if the `selector` provided to `AutoComplete` does not match an existing DOM element, or if the element is not yet available when the AutoComplete instance is created.

fix Verify that the `selector` (e.g., `'#search-field'`) accurately targets an existing HTML input element. Ensure that the `new AutoComplete()` call is deferred until the DOM is fully loaded, typically by placing the script at the end of `<body>` or wrapping it in a `DOMContentLoaded` event listener.

Warnings

breaking This library is no longer actively maintained. The last release was in 2016 (v1.0.5), meaning it does not receive updates for new JavaScript features, browser changes, or security vulnerabilities.
Fix: Consider migrating to a modern, actively maintained autocomplete library (e.g., Algolia Autocomplete, Headless UI Combobox, or a framework-specific solution) for security, compatibility, and feature updates.
gotcha The library is designed for global scope usage via a <script> tag and does not natively support ES Modules (`import`/`export`). Integrating it into modern JavaScript module environments (e.g., Webpack, Vite, Rollup) requires a bundler to correctly handle its UMD/CommonJS output.
Fix: Ensure your bundler is configured to correctly import CommonJS/UMD modules. Alternatively, use it as a global script for simpler setups. For TypeScript, manual declaration files (`.d.ts`) would be required.
gotcha The library has no official TypeScript type definitions. Using it in a TypeScript project will require creating custom declaration files (`.d.ts`) to avoid type errors.
Fix: Create a `declarations.d.ts` file in your project: `declare class AutoComplete { constructor(options: any); }` and define types for the options object as needed.

Install

npm install javascript-autocomplete npm
yarn add javascript-autocomplete yarn
pnpm add javascript-autocomplete pnpm

Imports

AutoComplete

<script src="path/to/auto-complete.min.js"></script>
<script>
  new AutoComplete({
    selector: '#my-input',
    minChars: 1,
    source: function(term, suggest) { /* ... */ }
  });
</script>

The library primarily exposes a global `AutoComplete` constructor when included via a <script> tag. It's designed for vanilla JS environments.

AutoComplete (CommonJS)

wrong:

import AutoComplete from 'javascript-autocomplete'; // Incorrect for older Node.js/bundlers

correct:

const AutoComplete = require('javascript-autocomplete');

new AutoComplete({
  selector: '#my-input',
  minChars: 1,
  source: function(term, suggest) { /* ... */ }
});

While not officially documented for module systems, for older Node.js or bundlers configured for CommonJS, it might be accessible via `require`. However, its design is pre-ESM.

AutoComplete (ESM Bundled)

wrong:

import { AutoComplete } from 'javascript-autocomplete'; // No named export provided natively

correct:

// Assuming a bundler is configured to handle CJS or a UMD build is used
import AutoComplete from 'javascript-autocomplete';

new AutoComplete({
  selector: '#my-input',
  minChars: 1,
  source: function(term, suggest) { /* ... */ }
});

The library does not provide native ES Modules exports. If used in a modern ESM project, it typically requires a bundler (like Webpack or Rollup) to process its CommonJS/UMD output, which often results in a default import.

Quickstart

This quickstart demonstrates how to initialize the `AutoComplete` library on an input field using a static array as the data source and logs the selected item to the console.

<html>
<head>
  <title>JavaScript AutoComplete Demo</title>
  <style>
    .autocomplete-suggestions {
      border: 1px solid #999;
      background: #FFF;
      overflow: auto;
      max-height: 200px;
      position: absolute;
      z-index: 9999;
    }
    .autocomplete-suggestion {
      padding: 2px 5px;
      white-space: nowrap;
      overflow: hidden;
    }
    .autocomplete-selected {
      background: #F0F0F0;
    }
    .autocomplete-suggestions strong {
      font-weight: normal;
      color: #3399FF;
    }
  </style>
</head>
<body>
  <h1>Search Programming Languages</h1>
  <input type="text" id="search-field" placeholder="Type a language...">

  <script src="https://goodies.pixabay.com/javascript/auto-complete/auto-complete.min.js"></script>
  <script>
    const languages = [
      'ActionScript', 'AppleScript', 'Asp', 'BASIC', 'C', 'C++', 'Clojure', 'CSS', 'Erlang', 
      'Go', 'Groovy', 'Haskell', 'HTML', 'Java', 'JavaScript', 'Lisp', 'Perl', 'PHP', 
      'Python', 'Ruby', 'Scala', 'Scheme', 'Swift', 'TypeScript', 'Rust', 'Kotlin'
    ];

    new AutoComplete({
      selector: '#search-field',
      minChars: 1,
      delay: 150,
      source: function(term, suggest){
        term = term.toLowerCase();
        const suggestions = languages.filter(lang => lang.toLowerCase().includes(term));
        suggest(suggestions);
      },
      onSelect: function(event, term, item){
        console.log('Selected:', term);
        // Optionally do something with the selected term, e.g., navigate or update other fields
      }
    });
  </script>
</body>
</html>

view raw JSON →