Lightweight & Fast JavaScript Autocomplete Library – Luggest

Luggest is a lightweight, fast, dependency-free autocomplete library for vanilla JavaScript that supports both static arrays and remote JSON sources.

The library uses an instance-based architecture similar to CKEditor or TinyMCE. Each input element gets its own instance that you can access and control programmatically.

Features:

• Flexible Data Formats: Accepts simple string arrays or structured objects with value, label, and metadata properties.
• Keyboard Navigation: Full arrow key support with Enter to select and Escape to close.
• Highly Customizable: Set minimum input length (including 0 for show-all-on-focus), maximum results, and custom callbacks.
• Event Hooks: Callbacks for opening the dropdown and selecting items.

Use Cases:

• Search Forms: Add autocomplete to search inputs that query your backend API for suggestions as users type.
• City/Location Selectors: Provide typeahead filtering for geographic data without loading massive datasets upfront.
• Tag Input Systems: Build tag selection UI where users pick from existing tags or see suggestions based on partial matches.
• Form Autocomplete: Replace traditional select dropdowns with searchable inputs for better user experience on long option lists.

How To Use It:

1. Download the luggest.js file and insert it into your web project. The library automatically creates a global Luggest object. You can access it immediately after the script loads.

<link rel="stylesheet" href="/src/luggest.css">
<script src="/src/luggest.js"></script>

2. Create an input element with autocomplete disabled.

<input type="text" id="languages" autocomplete="off">

3. Define your data source as a JS array.

const techStack = [
  { label: 'JavaScript', value: 'js', metadata: { react: 123, vue: 345 } },
  { label: 'TypeScript', value: 'ts' },
  { label: 'Python', value: 'py' },
  { label: 'Rust', value: 'rs' },
  { label: 'Go', value: 'go' },
  { label: 'C++', value: 'cpp' },
  { label: 'Java', value: 'java' },
  { label: 'Ruby', value: 'rb' },
  { label: 'PHP', value: 'php' },
  { label: 'Swift', value: 'swift' },
  { label: 'Kotlin', value: 'kt' },
  { label: 'Dart', value: 'dart' }
];

// OR a simple array
const techStack = [
  'JavaScript', 'CSS3', 'HTML5', ...
];
4. Initialize Luggest on the input element you just created.

Luggest.init('#languages', {
  source: techStack, 
  on_select: function (element, item) {
    // This callback fires when user selects an item
    console.log('Selected:', item);
    // item contains: { value, label, metadata }
  }
});

5. For remote data sources, pass a URL string as the source option. Luggest appends a term query parameter with the user’s input. Your server endpoint must return a JSON array. The array can contain simple strings or objects with value/label/metadata properties.

Luggest.init('#languages', {
  source: '/api/',
  // more options here
});

6. All configuration options.

• source (Array or String): The data source for autocomplete suggestions. Pass an array of strings, an array of objects with value/label/metadata properties, or a URL string for AJAX requests. When using a URL, Luggest appends ?term=USER_INPUT to your endpoint. Your server must return a JSON array.
• min_length (Number): The minimum number of characters required before suggestions appear. Default is 1. Set to 0 to show all suggestions when the input receives focus. This creates a dropdown-like behavior where filtering happens as the user types.
• max_results (Number): The maximum number of items to display in the dropdown. Default is 20. This prevents performance issues with large result sets. The library stops rendering after reaching this limit.
• on_open (Function): Callback function that fires when the dropdown opens with suggestions. Receives two parameters: element (the input DOM element) and items (array of normalized suggestion objects). Use this to track analytics or modify the UI.
• on_select (Function): Callback function that fires when the user selects an item by clicking or pressing Enter. Receives two parameters: element (the input DOM element) and item (the selected item object with value, label, and metadata properties). The input value is automatically updated with item.value before this callback runs.

Luggest.init('#languages', {
  source: [],
  min_length: 1,
  max_results: 20,
  on_open: null,
  on_select: null,
});

7. API methods.

// Get a reference to an existing instance by input id
const instance = Luggest.get('languages');
// Close the dropdown programmatically
// This hides the suggestion list and resets the highlight index
instance.close();
// Completely destroy the instance
// Removes event listeners, deletes the dropdown from DOM
// Unregisters the instance from Luggest.instances
// Clears the data-luggest attribute from the element
instance.destroy();
// Access instance by id
const inst = Luggest.instances['languages'];

Related Resources:

• 10 Best Autocomplete Libraries In Vanilla JavaScript

FAQs:

Q: Can I style the dropdown to match my site’s design?
A: Yes. The dropdown has the class luggest-dropdown and each item has the class luggest-item. Highlighted items get the is-active class. Target these classes in your CSS.

Q: How do I prevent the dropdown from opening on every keystroke for long result sets?

A: Increase the min_length option to require more characters before querying. For AJAX sources, this reduces server load. You can also use max_results to cap the number of displayed items.

Q: What happens if my AJAX endpoint returns an error or invalid JSON?
A: Luggest catches fetch errors and logs them to the console. The dropdown simply won’t open. Your endpoint should return a proper JSON array even for empty results. Return [] instead of error responses when there are no matches.

Q: Can I initialize Luggest on dynamically created inputs?
A: Yes. Call Luggest.init() after inserting the input into the DOM. If you remove the input later, call destroy() on the instance to clean up event listeners and prevent memory leaks.