Ark Autocomplete

A lightweight, customizable, and easy-to-use autocomplete library for JavaScript.

Features

• 🔍 Smart Filtering: Customizable filtering function for precise search results
• 🎨 Customizable Templates: Flexible item rendering with template functions
• ⌨️ Keyboard Navigation: Intuitive arrow key and Enter key support
• 📱 Responsive Design: Automatically positions dropdown based on input element
• ⚡ Debounced Input: Optimized performance with built-in debouncing
• 🎯 Event Handling: Comprehensive event system for selection and change tracking
• 🔧 Easy Integration: Simple setup with extensive configuration options

Installation

Include the library directly in your HTML:

<script src="path/to/ark-autocomplete.js"></script>

Quick Start

// Basic usage with array of strings
ark_autocomplete({
  target: '#my-input',
  data: ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']
});

// Advanced usage with objects
ark_autocomplete({
  target: '#customer-search',
  data: customers,
  filter: searchTerm => customers.filter(
    customer => customer.name.toLowerCase().includes(searchTerm.toLowerCase())
  ),
  display: 'name',
  value: 'id'
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | target | String/Element | null | CSS selector or DOM element to attach autocomplete | | data | Array | [] | Data source for autocomplete | | filter | Function | Basic string matching | Custom filtering function | | item_templ | Function | <strong>${item}</strong> | Function to render each item | | compare | Function | Value comparison | Function to compare selected item with input | | value | String | '' | Property name for value field (when using objects) | | display | String | '' | Property name for display field (when using objects) |

API Methods

Instance Methods

const autocomplete = ark_autocomplete({ /* options */ });

// Subscribe to events
autocomplete.on('selected', (inputElement, selectedItem) => {
  console.log('Item selected:', selectedItem);
});

// Programmatically select an item
autocomplete.select(item);

// Get current value
const value = autocomplete.get_value();

// Unsubscribe from events
autocomplete.off('selected', callbackFunction);

Events

• selected: Triggered when an item is selected
• changed: Triggered when the value changes

Examples

Basic String Array

ark_autocomplete({
  target: '#fruit-search',
  data: ['Apple', 'Apricot', 'Avocado', 'Banana', 'Blueberry']
});

Custom Object Array

const users = [
  { id: 1, name: 'John Doe', email: '[email protected]' },
  { id: 2, name: 'Jane Smith', email: '[email protected]' }
];

ark_autocomplete({
  target: '#user-search',
  data: users,
  filter: searchTerm => users.filter(
    user => user.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
            user.email.toLowerCase().includes(searchTerm.toLowerCase())
  ),
  item_templ: user => `
    <div>
      <strong>${user.name}</strong>
      <br>
      <small>${user.email}</small>
    </div>
  `,
  display: 'name',
  value: 'id'
});

Custom Filter Function

ark_autocomplete({
  target: '#custom-filter',
  data: products,
  filter: searchTerm => {
    // Your custom filtering logic
    return products.filter(product => 
      product.name.includes(searchTerm) || 
      product.category.includes(searchTerm) ||
      product.tags.some(tag => tag.includes(searchTerm))
    );
  }
});

Styling

The autocomplete dropdown uses the following CSS classes that you can customize:

• .autocomplete-items - The dropdown container
• .autocomplete-items div - Individual items
• .autocomplete-items div:hover - Hover state
• .autocomplete-active - Currently selected item with keyboard

Override these styles in your CSS to match your application's design.

Browser Compatibility

Works in all modern browsers that support:

• ES6+ JavaScript features
• CSS Flexbox
• DOM Events

License

Copyright (c) 2015-2028 Immanuel R

Author

Immanuel R

• Website: https://www.immanuel.co
• GitHub: https://github.com/immi5556
• NPM: https://www.npmjs.com/~immi5556

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For support, bug reports, or feature requests, please open an issue on the GitHub repository.