searchable-select-js

v0.0.1

Published

7 months ago

A lightweight, dependency-free searchable select component that enhances native HTML select elements.

0High
0Medium
0Low

miloudimohamed

select dropdown searchable autocomplete form input ui component

Searchable Select

A lightweight, dependency-free searchable select component that progressively enhances native HTML <select> elements.

Features

✅ Progressive Enhancement - Works with native HTML selects
✅ Zero Dependencies - Pure vanilla JavaScript
✅ Single & Multiple Selection - Automatic detection via multiple attribute
✅ Server-Side Search - Built-in AJAX support with debouncing
✅ Keyboard Accessible - Full keyboard navigation support
✅ Form Compatible - Native form submission with proper name attribute
✅ Lightweight - < 10KB minified

Installation

npm install searchable-select

Usage

Basic Setup

<!-- Include CSS -->
<link rel="stylesheet" href="node_modules/searchable-select/dist/searchable-select.min.css">

<!-- Your HTML -->
<select name="fruit" data-placeholder="Choose a fruit...">
    <option value="">Select...</option>
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="cherry">Cherry</option>
</select>

<!-- Include JS -->
<script src="node_modules/searchable-select/dist/searchable-select.min.js"></script>
<script>
    // Initialize all selects
    SearchableSelect.autoInit();
</script>

With Module Bundler

import SearchableSelect from 'searchable-select';
import 'searchable-select/dist/searchable-select.css';

// Auto-initialize all selects
SearchableSelect.autoInit();

// Or initialize specific select
const mySelect = document.querySelector('#my-select');
new SearchableSelect(mySelect);

Auto-Initialize

Add data-auto-init attribute to your HTML:

<html data-auto-init="searchable-select">
    <!-- Your selects will be automatically initialized -->
</html>

Configuration

All configuration is done via data-* attributes on your <select> element:

| Attribute | Description | Default | |-----------|-------------|---------| | data-placeholder | Placeholder text | "Select an option..." | | data-search-placeholder | Search input placeholder | "Search..." | | data-search-url | URL for server-side search | null | | data-search-delay | Debounce delay in ms | 300 | | data-loading-text | Loading message | "Loading..." | | data-no-results-text | No results message | "No results found" |

Examples

Single Select

<select name="country" data-placeholder="Choose a country...">
    <option value="">Select...</option>
    <option value="us">United States</option>
    <option value="uk">United Kingdom</option>
    <option value="ca">Canada</option>
</select>

Multiple Select

<select name="colors[]" 
        multiple 
        data-placeholder="Choose colors...">
    <option value="red">Red</option>
    <option value="blue">Blue</option>
    <option value="green">Green</option>
</select>

Server-Side Search

<select name="user" 
        data-placeholder="Search users..."
        data-search-url="/api/users/search"
        data-search-delay="500">
    <option value="">Start typing...</option>
</select>

Server Response Format:

[
    { "value": "1", "label": "John Doe" },
    { "value": "2", "label": "Jane Smith" }
]

Pre-selected Values

<select name="size">
    <option value="">Select...</option>
    <option value="s">Small</option>
    <option value="m" selected>Medium</option>
    <option value="l">Large</option>
</select>

Disabled Options

<select name="product">
    <option value="">Select...</option>
    <option value="item1">Available Item</option>
    <option value="item2" disabled>Out of Stock</option>
</select>

API

Methods

const select = document.querySelector('#my-select');
const instance = new SearchableSelect(select);

// Refresh the component (after adding/removing options)
instance.refresh();

// Destroy the component
instance.destroy();

// Access the instance from the select element
select.searchableSelect.refresh();

Static Methods

// Initialize all selects on the page
SearchableSelect.autoInit();

// Initialize specific selects
SearchableSelect.autoInit('select.custom-class');

🗺️ Roadmap

[ ] Accessibility
[ ] Keyboard navigation
[ ] TypeScript support
[ ] Right-to-left (RTL) support

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.