multi-selectbox-js

v1.2.0

Published

4 months ago

A lightweight, vanilla JavaScript library for creating interactive multi-select dropdowns with tag-based UI

Downloads

0High
0Medium
0Low

sanju9645

multi-select dropdown select tags javascript vanilla-js ui component form input

Multi-SelectBox JS

A lightweight, vanilla JavaScript library for creating interactive multi-select dropdowns with tag-based UI.

🎮 View Live Demo

Credits

This library is inspired by and built upon the excellent work of Habib Mhamadi's multi-select-tag repository. We've enhanced the original implementation with additional features and customizations:

Original Features (from multi-select-tag):

Multi-select functionality with search and filter
Tag-based UI with remove functionality
Keyboard navigation support
Automatic synchronization with hidden select elements

Additional Features & Enhancements:

Color Customization: Full control over colors for all UI elements
Tag Display Management: Interactive "+ X more" indicator with dropdown
Class-based Architecture: Refactored to modern JavaScript class structure
Auto CSS Injection: No manual CSS imports required
NPM Package: Published as a reusable npm package
Enhanced Documentation: Comprehensive examples and API documentation
Instance-Specific Styling: Each dropdown can have unique color schemes

Thank you to Habib Mhamadi for the original inspiration and foundation!

Features

Search & Filter: Filter options dynamically as you type
Keyboard Navigation: Use arrow keys to navigate and Enter to select
Tag Display Control: Limit visible tags with interactive "+ X more" indicator
Automatic Sync: All changes sync with the hidden <select> element
Public API: Helper methods selectAll(), clearAll(), and getSelectedTags()
Multiple Instances: Each instance is independent and encapsulated with unique IDs
No Dependencies: Pure vanilla JavaScript with no external dependencies
Auto CSS Injection: CSS is automatically loaded - no manual CSS import needed
Form-Ready: Multiple select boxes can be used in a single form without conflicts

Installation

NPM

npm install multi-selectbox-js

CDN

<script src="https://unpkg.com/[email protected]/dist/multi-selectbox-js.js"></script>

Direct File Usage (after npm install)

If you've installed the package via npm, you can also use it directly in HTML files:

<script src="node_modules/multi-selectbox-js/dist/multi-selectbox-js.js"></script>

Quick Start

Method 1: NPM Installation

npm install multi-selectbox-js

<!DOCTYPE html>
<html>
<head>
    <!-- CSS is automatically injected by the JS file -->
    <script src="node_modules/multi-selectbox-js/dist/multi-selectbox-js.js"></script>
</head>
<body>
    <select id="countries" multiple>
        <option value="us">United States</option>
        <option value="uk">United Kingdom</option>
        <option value="ca">Canada</option>
        <option value="au">Australia</option>
    </select>

    <script>
        const multiSelect = new MultiSelectBox('countries', {
            placeholder: 'Select countries...',
            maxDisplayTags: 2
        });
    </script>
</body>
</html>

Method 2: CDN Usage

<!DOCTYPE html>
<html>
<head>
    <!-- CSS is automatically injected by the JS file -->
    <script src="https://unpkg.com/[email protected]/dist/multi-selectbox-js.js"></script>
</head>
<body>
    <select id="countries" multiple>
        <option value="us">United States</option>
        <option value="uk">United Kingdom</option>
        <option value="ca">Canada</option>
        <option value="au">Australia</option>
    </select>

    <script>
        const multiSelect = new MultiSelectBox('countries', {
            placeholder: 'Select countries...',
            maxDisplayTags: 2
        });
    </script>
</body>
</html>

Method 3: Module Import

// ES6 Modules
import MultiSelectBox from 'multi-selectbox-js';

// CommonJS
const MultiSelectBox = require('multi-selectbox-js');

const multiSelect = new MultiSelectBox('countries', {
    placeholder: 'Select countries...',
    maxDisplayTags: 2
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | placeholder | string | 'Search' | Placeholder text for the input field | | maxSelection | number | Infinity | Maximum number of items that can be selected | | maxDisplayTags | number | Infinity | Maximum number of visible tags (shows "+ X more" for overflow) | | required | boolean | false | Whether the field is required | | onChange | function | null | Callback function when selection changes | | addAllOption | boolean | false | Enable/disable the "All" option functionality | | allOptionText | string | 'Select All' | Custom text for the "All" option display |

Examples

Basic Usage

const multiSelect = new MultiSelectBox('mySelect', {
    placeholder: 'Choose options...'
});

With Display Limit

const multiSelect = new MultiSelectBox('mySelect', {
    maxDisplayTags: 1,  // Show only 1 tag + "+ X more"
    placeholder: 'Select items...'
});

With Selection Limit

const multiSelect = new MultiSelectBox('mySelect', {
    maxSelection: 5,    // Allow only 5 selections
    maxDisplayTags: 3,  // Show 3 tags + "+ X more"
    onChange: (tags) => console.log('Selected:', tags)
});

With "All" Option

const multiSelect = new MultiSelectBox('mySelect', {
    addAllOption: true,           // Enable "All" option
    allOptionText: 'Select All',  // Custom text for "All" option
    maxDisplayTags: 3,
    onChange: (tags) => console.log('Selected:', tags)
});

Public API

Methods

`selectAll()`

Selects all available options (respects maxSelection limit).

multiSelect.selectAll();

`clearAll()`

Clears all selections.

multiSelect.clearAll();

`getSelectedTags()`

Returns an array of currently selected tags.

const selected = multiSelect.getSelectedTags();
console.log(selected); // [{id: 'us', label: 'United States'}, ...]

"All" Option Functionality

When addAllOption: true is enabled, the MultiSelectBox provides intelligent "All" option management:

Features:

Auto-placement: "All" option always appears first in the dropdown and selections
Smart selection: Selecting "All" automatically selects all other options
Smart deselection: Deselecting "All" clears all selections
Auto-management: Selecting all individual options automatically adds "All"
Mutual exclusivity: Selecting individual options when "All" is selected removes "All"
Custom text: Use allOptionText to customize the display text

Behavior Examples:

// When "All" is selected
// All other options are automatically selected
// "All" appears first in the selected tags list

// When individual options are selected
// If all individual options become selected, "All" is automatically added

// When "All" is deselected
// All other selections are cleared

// When individual options are deselected from "All"
// "All" is automatically removed, other selections remain

Multiple Instances in Forms

You can use multiple MultiSelectBox instances in a single form without any conflicts. Each instance gets unique IDs automatically:

<form>
    <select id="countries" multiple>
        <option value="us">United States</option>
        <option value="uk">United Kingdom</option>
        <option value="ca">Canada</option>
    </select>
    
    <select id="languages" multiple>
        <option value="js">JavaScript</option>
        <option value="py">Python</option>
        <option value="java">Java</option>
    </select>
    
    <select id="colors" multiple>
        <option value="red">Red</option>
        <option value="blue">Blue</option>
        <option value="green">Green</option>
    </select>
</form>

<script>
    // Each instance works independently with unique IDs
    const countriesSelect = new MultiSelectBox('countries', {
        maxSelection: 3,
        placeholder: 'Select countries...'
    });
    
    const languagesSelect = new MultiSelectBox('languages', {
        maxDisplayTags: 1,
        placeholder: 'Select languages...'
    });
    
    const colorsSelect = new MultiSelectBox('colors', {
        colors: {
            tagBackground: '#ff6b6b',
            tagText: '#ffffff'
        },
        placeholder: 'Select colors...'
    });
</script>

Key Benefits:

No ID Conflicts: Each instance gets unique internal IDs
Independent Functionality: Each dropdown works completely independently
Individual Styling: Each instance can have its own color scheme
Form Submission: All selected values are properly synced to the original <select> elements

Interactive Features

Tag Display Management

Clickable "+ X more" indicator: Click to view all selected tags
Individual tag removal: Click the × button next to any tag to remove it
Automatic dropdown hiding: The dropdown closes when all tags are removed
Consistent styling: Follows the same design patterns as the main dropdown

Keyboard Navigation

Arrow Up/Down: Navigate through dropdown options
Enter: Select highlighted option
Backspace: Remove last selected tag (when input is empty)

Color Customization

You can customize the colors of various elements using the colors configuration option:

const multiSelect = new MultiSelectBox('mySelect', {
    colors: {
        // Container colors
        containerBorder: '#e5e7eb',
        containerBackground: '#ffffff',
        
        // Tag colors
        tagBackground: '#DBEAFE',
        tagText: '#1E40AF',
        tagBorder: '#3B82F6',
        
        // Dropdown colors
        dropdownBorder: '#e5e7eb',
        dropdownBackground: '#ffffff',
        dropdownItemBackground: '#E5E7EB',
        dropdownItemText: '#374151',
        
        // More indicator colors
        moreIndicatorBackground: '#F3F4F6',
        moreIndicatorText: '#6B7280',
        
        // Selected tag dropdown colors
        selectedTagDropdownBackground: '#ffffff',
        selectedTagDropdownText: '#1E40AF',
        selectedTagDropdownHover: '#f9fafb'
    }
});

Available Color Options

| Color Option | Description | Default | |--------------|-------------|---------| | containerBorder | Border color of the main container | #e5e7eb | | containerBackground | Background color of the main container | #ffffff | | tagBackground | Background color of selected tags | #DBEAFE | | tagText | Text color of selected tags | #1E40AF | | tagBorder | Border color of selected tags | #3B82F6 | | dropdownBorder | Border color of the dropdown | #e5e7eb | | dropdownBackground | Background color of the dropdown | #ffffff | | dropdownItemBackground | Background color of dropdown items on hover | #E5E7EB | | dropdownItemText | Text color of dropdown items | #374151 | | moreIndicatorBackground | Background color of "+ X more" indicator | #F3F4F6 | | moreIndicatorText | Text color of "+ X more" indicator | #6B7280 | | selectedTagDropdownBackground | Background color of selected tags dropdown | #ffffff | | selectedTagDropdownText | Text color of selected tags in dropdown | #1E40AF | | selectedTagDropdownHover | Background color of selected tags on hover in dropdown | #f9fafb |

Color Customization Examples

Dark Theme:

const multiSelect = new MultiSelectBox('mySelect', {
    colors: {
        containerBorder: '#374151',
        containerBackground: '#1F2937',
        tagBackground: '#3B82F6',
        tagText: '#ffffff',
        dropdownBackground: '#1F2937',
        dropdownItemBackground: '#374151',
        dropdownItemText: '#ffffff'
    }
});

Custom Brand Colors:

const multiSelect = new MultiSelectBox('mySelect', {
    colors: {
        tagBackground: '#FF6B6B',
        tagText: '#ffffff',
        moreIndicatorBackground: '#4ECDC4',
        moreIndicatorText: '#ffffff'
    }
});

CSS Handling

The library automatically injects the required CSS when loaded. You don't need to manually import any CSS files.

Automatic CSS Injection

NPM Package: CSS is automatically loaded from CDN
CDN Usage: CSS is automatically loaded from the same CDN
Direct File Usage: CSS is automatically loaded from CDN

Manual CSS Import (Optional)

If you prefer to import CSS manually, you can do so:

// Import CSS manually (optional)
import 'multi-selectbox-js/dist/multi-selectbox-js.css';

<!-- Manual CSS import (optional) -->
<link rel="stylesheet" href="node_modules/multi-selectbox-js/dist/multi-selectbox-js.css">

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Changelog

v1.0.0

Initial release
Multi-select functionality with search
Tag display management with "+ X more" indicator
Keyboard navigation support
Public API methods