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.

The post Lightweight & Fast JavaScript Autocomplete Library – Luggest appeared first on CSS Script.