autoComplete.js Documentation

autoComplete.js is a lightweight, pure vanilla JavaScript autocomplete and autosuggest library with zero dependencies. It is designed for speed and versatility, working seamlessly with <input>, <textarea>, and contentEditable elements.

Key Technical Specifications:

• Size: ~9 KB minified (~3.7 KB gzipped).
• Dependencies: Zero runtime dependencies.
• Search Engine: Supports strict (substring) and loose (scattered character) matching modes.
• Accessibility: WAI-ARIA 1.2 compliant.
• Features: Diacritics support, debouncing, async data sources, lifecycle events, and a plugin API.

autoComplete.js is a lightweight, pure vanilla JavaScript library designed for speed and versatility. Key features include:

• Zero Dependencies: Extremely lightweight (~3.7 KB gzip).
• Versatile Input Support: Works with <input>, <textarea>, and contentEditable elements.
• Powerful Search: Supports two different search modes and diacritics.
• Performance: Includes built-in debounce support.
• Extensibility: Provides a useful plugin API and lifecycle events.
• Accessibility: WAI-ARIA compliant.
• Customizable: Highly configurable to match your project's design.

Use the following comparison to determine if autoComplete.js fits your project requirements based on size, dependencies, and framework support.

For technical questions, troubleshooting, or implementation issues related to autoComplete.js, please post your questions on Stack Overflow using the autoCompletejs tag.

https://stackoverflow.com/questions/tagged/autoCompletejs

autoComplete.js

Pure vanilla JavaScript autocomplete for <input>, <textarea>, and contentEditable elements. Configuration-driven with sensible defaults. Works anywhere: plain HTML, WordPress, Django, Rails, any SPA framework, or no framework at all. The smallest full-featured option in the category.

Best for: Projects that need a lightweight, framework-free autocomplete with zero setup friction.

Key Advantages

• Small footprint: 4-7x smaller than comparable libraries with zero dependencies.
• Framework independent: Works with React, Vue, Svelte, Angular, or no framework.
• Zero build step: Can be loaded via CDN and configured with a single object.
• Accessibility: WAI-ARIA 1.2 combobox pattern implemented out of the box.
• Search flexibility: Supports two search modes (strict and loose) and custom search engines.

To get started with autoComplete.js, follow these three steps:

1. Prepare an HTML element: Create an <input>, <textarea>, or any HTML tag with a contenteditable attribute and assign it a unique identifier (e.g., id="autoComplete").
2. Include the library: Add the autoComplete.js library script to your page.
3. Initialize the instance: Add a configured instance of autoComplete.js to your page using JavaScript.

Depending on your configuration, use one of the following methods to update data:

1. If data.cache is false (default): The data.src function is called on every search, so it will automatically pick up new data from your source.
2. If data.cache is true: Update the internal store directly via autoCompleteJS.data.store = newDataArray;.
3. Re-initialization: Call unInit() followed by init() to apply a completely new configuration.

// Update cached data
autoCompleteJS.data.store = newDataArray;

To prevent the suggestion list from being cut off at the bottom of the viewport, use the events.input.open callback to calculate the position of the input and the list. If the list would exceed the window height, adjust its style to appear above the input instead of below it.

// autoComplete.js Config Options
events: {
    input: {
        open() {
            const position =
                autoCompleteJS.input.getBoundingClientRect().bottom + autoCompleteJS.list.getBoundingClientRect().height >
                (window.innerHeight || document.documentElement.clientHeight);

            if (position) {
                autoCompleteJS.list.style.bottom = autoCompleteJS.input.offsetHeight + 8 + "px";
            } else {
                autoCompleteJS.list.style.bottom = -autoCompleteJS.list.offsetHeight - 8 + "px";
            }
        },
    },
},

You can include autoComplete.js in your project using a CDN script tag for HTML or by importing it as a module in JavaScript environments.

HTML (CDN)

Add the script tag to your <body>:

<script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@{{version}}/dist/autoComplete.min.js"></script>

JavaScript (NPM)

Use CommonJS or ES6 modules:

// CommonJS
const autoComplete = require("@tarekraafat/autocomplete.js");

/* OR */

// ES6 modules
import autoComplete from "@tarekraafat/autocomplete.js";

When using an asynchronous data.src function, ensure you handle potential errors to prevent silent failures.

If data.src fails (rejects or returns non-array-like data), the library will emit an error event. You should listen for this event to provide user feedback.

Recommended Pattern: Wrap your data.src logic in a try/catch block and ensure it returns an array-like structure on success.

You can install the library using npm or yarn to manage it as a dependency in your project.

npm i @tarekraafat/autocomplete.js

# or

yarn add @tarekraafat/autocomplete.js