SmartAutocomplete

A powerful, lightweight vanilla JavaScript autocomplete plugin with advanced features like fuzzy search, async data loading, and custom rendering.

Features

• 🚀 Zero dependencies
• 📦 Lightweight (minified + gzipped < 5KB)
• 🔍 Fuzzy search support
• ⚡ Async data loading
• 🎨 Custom item rendering
• ⌨️ Keyboard navigation
• 🔄 Debounced search
• 📱 Mobile-friendly
• 🎯 TypeScript support
• 🎨 Customizable styling

Installation

npm install smart-autocomplete

Or include it directly in your HTML:

<script src="https://unpkg.com/smart-autocomplete/dist/smart-autocomplete.js"></script>

Usage

Basic Usage

import SmartAutocomplete from 'smart-autocomplete';

const autocomplete = new SmartAutocomplete({
    input: document.getElementById('my-input'),
    data: [
        { label: 'Option 1', value: 1 },
        { label: 'Option 2', value: 2 },
        // ... more options
    ]
});

Async Data Loading

const autocomplete = new SmartAutocomplete({
    input: document.getElementById('my-input'),
    data: async (query) => {
        const response = await fetch(`/api/search?q=${query}`);
        const data = await response.json();
        return data.map(item => ({
            label: item.name,
            value: item.id
        }));
    },
    debounceTime: 300
});

Custom Rendering

const autocomplete = new SmartAutocomplete({
    input: document.getElementById('my-input'),
    data: items,
    customRender: (item) => `
        <div class="custom-item">
            <img src="${item.avatar}" alt="${item.label}">
            <span>${item.label}</span>
        </div>
    `
});

Fuzzy Search

const autocomplete = new SmartAutocomplete({
    input: document.getElementById('my-input'),
    data: items,
    fuzzySearch: true
});

API Reference

Options

Option	Type	Default	Description
input	HTMLInputElement	-	The input element to attach the autocomplete to
data	Array<{label: string, value: any}> | ((query: string) => Promise<Array<{label: string, value: any}>>)	-	Static data array or async function that returns data
minChars	number	2	Minimum characters required to trigger search
debounceTime	number	300	Debounce time in milliseconds for search
maxResults	number	10	Maximum number of results to show
onSelect	(item: {label: string, value: any}) => void	-	Callback function when an item is selected
onSearch	(query: string) => void	-	Callback function when search is performed
placeholder	string	'Search...'	Placeholder text for the input
noResultsText	string	'No results found'	Text to show when no results are found
loadingText	string	'Loading...'	Text to show while loading results
highlightMatches	boolean	true	Whether to highlight matching text
caseSensitive	boolean	false	Whether search should be case sensitive
fuzzySearch	boolean	false	Whether to use fuzzy search
customRender	(item: {label: string, value: any}) => string	-	Custom render function for items
position	'bottom' | 'top'	'bottom'	Position of the dropdown
width	string	'100%'	Width of the autocomplete container
zIndex	number	1000	z-index of the dropdown

Methods

Method	Description
destroy()	Removes the autocomplete instance and cleans up event listeners

Events

The plugin emits the following events on the input element:

• smart-autocomplete:select - Fired when an item is selected
• smart-autocomplete:search - Fired when a search is performed
• smart-autocomplete:open - Fired when the dropdown opens
• smart-autocomplete:close - Fired when the dropdown closes

Keyboard Navigation

• ↑ / ↓ - Navigate through results
• Enter - Select the current result
• Escape - Close the dropdown

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• IE11 (with polyfills)

Contributing

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

License

MIT License - see the LICENSE file for details.