multi-selector-dropdown

Multi-Selector Dropdown

A powerful React component for multi-select dropdown with API-driven options, search capability, and add new option functionality. Built with TypeScript and designed for modern React applications.

✨ Features

• 🚀 API-Driven Options: Fetch options dynamically from external APIs
• 🔍 Search Capability: Real-time search and filtering of options
• ➕ Add New Option: Add new values to the database if not found
• 📋 Multi-Selection Support: Select multiple options simultaneously
• ⚡ TypeScript Support: Full TypeScript support with type definitions
• 🎨 Customizable: Highly configurable with various props and callbacks
• ♿ Accessible: Built with accessibility in mind
• 🛡️ Error Handling: Comprehensive error handling for API failures
• 📱 Responsive: Works seamlessly across different screen sizes
• ⚡ Performance Optimized: Debounced search and efficient rendering
• 🎯 Production Ready: Fully tested and ready for production use

📦 Installation

npm install multi-selector-dropdown

🔧 Dependencies

This package requires the following peer dependencies:

npm install react react-dom react-bootstrap-typeahead

CSS Import

You'll also need to import the required CSS in your application:

import 'react-bootstrap-typeahead/css/Typeahead.css';

📸 Snapshot

🚀 Basic Usage

A simple example showing the basic functionality of the component:

import { useState, useEffect } from 'react';
import { Typeahead } from 'react-bootstrap-typeahead';
import 'bootstrap/dist/css/bootstrap.min.css';
import 'react-bootstrap-typeahead/css/Typeahead.css';
import './App.css'; // Assuming you have some custom styles

interface UserOption {
  id: string | number;
  label: string;
}

function App() {
  const [selectedOptions, setSelectedOptions] = useState<UserOption[]>([]);
  const [options, setOptions] = useState<UserOption[]>([]);

  useEffect(() => {
    const dummyUsers: UserOption[] = [
      { id: '1', label: 'Alice Johnson' },
      { id: '2', label: 'Bob Smith' },
      { id: '3', label: 'Charlie Davis' },
      { id: '4', label: 'Diana Ross' },
      { id: '5', label: 'Ethan Brown' },
    ];
    setOptions(dummyUsers);
  }, []);

  const handleAddNew = (value: string): UserOption => {
    const newUser = { id: `new-${Date.now()}`, label: value };
    setOptions((prev) => [...prev, newUser]);
    return newUser;
  };

  return (
    <div className="min-vh-100 d-flex align-items-center justify-content-center bg-light">
      <div className="container p-4 rounded-4 shadow-lg" style={{ maxWidth: '900px', backgroundColor: '#ffffff' }}>
        <h2 className="text-center text-primary fw-bold mb-4">Multi-Selector Dropdown</h2>
        <p className="text-center text-muted mb-5">
          This example uses hardcoded data instead of fetching from an API.
        </p>

        <div className="row justify-content-center">
          <div className="col-md-10">
            <label className="form-label text-dark fw-semibold">Select Users*</label>
            <Typeahead
              id="user-multi-select"
              labelKey="label"
              multiple
              allowNew
              newSelectionPrefix="Add new user: "
              options={options}
              placeholder="Search and select users..."
              onChange={(selected: any[]) => {
                const cleanOptions: UserOption[] = selected.map((item) =>
                  typeof item === 'string' ? handleAddNew(item) : item
                );
                setSelectedOptions(cleanOptions);
              }}
              selected={selectedOptions}
              className="bg-white rounded-3 shadow-sm border border-secondary"
            />
          </div>
        </div>

        {selectedOptions.length > 0 && (
          <div className="mt-5">
            <h4 className="text-dark text-center fw-semibold mb-4">Selected Users</h4>
            <div className="table-responsive">
              <table className="table table-striped table-hover table-bordered">
                <thead className="table-primary">
                  <tr>
                    <th>ID</th>
                    <th>Name</th>
                  </tr>
                </thead>
                <tbody>
                  {selectedOptions.map((option) => (
                    <tr key={option.id} className="align-middle">
                      <td>{option.id}</td>
                      <td>{option.label}</td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
          </div>
        )}
      </div>
    </div>
  );
}

export default App;

🎯 Advanced Usage

A comprehensive example demonstrating advanced features like multiple dropdowns, different configurations, and complex state management:

import React, { useState } from 'react';
import MultiSelectorDropdown from 'multi-selector-dropdown';
import { Option } from 'multi-selector-dropdown';
import 'react-bootstrap-typeahead/css/Typeahead.css';

const AdvancedExample = () => {
  const [selectedUsers, setSelectedUsers] = useState<Option[]>([]);
  const [selectedProducts, setSelectedProducts] = useState<Option[]>([]);
  const [selectedCategories, setSelectedCategories] = useState<Option[]>([]);

  // Mock API function for adding new users
  const handleAddNewUser = async (value: string): Promise<Option | null> => {
    await new Promise(resolve => setTimeout(resolve, 300));
    return {
      id: `user-${Date.now()}`,
      label: value,
      type: 'user'
    };
  };

  // Mock API function for adding new products
  const handleAddNewProduct = async (value: string): Promise<Option | null> => {
    await new Promise(resolve => setTimeout(resolve, 300));
    return {
      id: `product-${Date.now()}`,
      label: value,
      type: 'product'
    };
  };

  // Mock API function for adding new categories
  const handleAddNewCategory = async (value: string): Promise<Option | null> => {
    await new Promise(resolve => setTimeout(resolve, 300));
    return {
      id: `category-${Date.now()}`,
      label: value,
      type: 'category'
    };
  };

  const handleUserChange = (options: Option[]) => {
    setSelectedUsers(options);
    console.log('Selected users:', options);
  };

  const handleProductChange = (options: Option[]) => {
    setSelectedProducts(options);
    console.log('Selected products:', options);
  };

  const handleCategoryChange = (options: Option[]) => {
    setSelectedCategories(options);
    console.log('Selected categories:', options);
  };

  return (
    <div className="container mt-5">
      <h2>Multi-Selector Dropdown - Advanced Example</h2>
      <p className="text-muted">
        This example demonstrates advanced features including multiple dropdowns, 
        different configurations, and complex state management.
      </p>
      
      <div className="row">
        <div className="col-md-4">
          <h4>Users Dropdown</h4>
          <MultiSelectorDropdown
            apiUrl="https://jsonplaceholder.typicode.com/users"
            placeholder="Search and select users..."
            label="Select Users"
            required={true}
            allowAddNew={true}
            addNewPrefix="Add new user: "
            onAddNew={handleAddNewUser}
            onChange={handleUserChange}
            multiple={true}
            maxSelections={3}
            clearButton={true}
            size="sm"
            error=""
            touched={false}
          />
        </div>

        <div className="col-md-4">
          <h4>Products Dropdown</h4>
          <MultiSelectorDropdown
            apiUrl="https://jsonplaceholder.typicode.com/posts"
            placeholder="Search and select products..."
            label="Select Products"
            required={false}
            allowAddNew={true}
            addNewPrefix="Add new product: "
            onAddNew={handleAddNewProduct}
            onChange={handleProductChange}
            multiple={true}
            maxSelections={5}
            clearButton={true}
            size="md"
            error=""
            touched={false}
          />
        </div>

        <div className="col-md-4">
          <h4>Categories Dropdown</h4>
          <MultiSelectorDropdown
            apiUrl="https://jsonplaceholder.typicode.com/albums"
            placeholder="Search and select categories..."
            label="Select Categories"
            required={false}
            allowAddNew={true}
            addNewPrefix="Add new category: "
            onAddNew={handleAddNewCategory}
            onChange={handleCategoryChange}
            multiple={false}
            clearButton={true}
            size="lg"
            error=""
            touched={false}
          />
        </div>
      </div>

      <div className="row mt-4">
        <div className="col-md-4">
          <h5>Selected Users ({selectedUsers.length})</h5>
          <ul className="list-group">
            {selectedUsers.map((user) => (
              <li key={user.id} className="list-group-item">
                <strong>ID:</strong> {user.id} | <strong>Name:</strong> {user.label}
              </li>
            ))}
          </ul>
        </div>

        <div className="col-md-4">
          <h5>Selected Products ({selectedProducts.length})</h5>
          <ul className="list-group">
            {selectedProducts.map((product) => (
              <li key={product.id} className="list-group-item">
                <strong>ID:</strong> {product.id} | <strong>Name:</strong> {product.label}
              </li>
            ))}
          </ul>
        </div>

        <div className="col-md-4">
          <h5>Selected Categories ({selectedCategories.length})</h5>
          <ul className="list-group">
            {selectedCategories.map((category) => (
              <li key={category.id} className="list-group-item">
                <strong>ID:</strong> {category.id} | <strong>Name:</strong> {category.label}
              </li>
            ))}
          </ul>
        </div>
      </div>

      <div className="mt-4">
        <h4>Summary</h4>
        <div className="alert alert-info">
          <strong>Total Selected Items:</strong> {selectedUsers.length + selectedProducts.length + selectedCategories.length}
          <br />
          <strong>Users:</strong> {selectedUsers.length} | 
          <strong>Products:</strong> {selectedProducts.length} | 
          <strong>Categories:</strong> {selectedCategories.length}
        </div>
      </div>
    </div>
  );
};

export default AdvancedExample;

🔧 Recent Updates & Fixes

✅ Version 1.0.3 - Production Ready

Major Improvements:

• 🔧 Fixed Dropdown UI Issues: Improved styling and dropdown appearance
• 🎯 Fixed Options Display: Options now appear correctly when clicking input field
• ⚡ Enhanced Search Functionality: Real-time search with proper debouncing
• 🛠️ Improved Add New Feature: Better handling of custom option creation
• 📱 Better Mobile Support: Enhanced responsive design
• 🧪 Comprehensive Testing: All tests passing (8/8)
• 📦 Build Optimization: Clean TypeScript compilation

Technical Fixes:

• Fixed selected={[]} prop to ensure dropdown shows options
• Improved filteredOptions logic for proper option filtering
• Enhanced search term state management
• Added proper error handling for API calls
• Optimized component re-rendering
• Fixed TypeScript type issues

API Reference

Props

Prop	Type	Default	Description
apiUrl	string	-	Required. The URL to fetch options from
apiMethod	'GET' | 'POST'	'GET'	HTTP method for API requests
apiHeaders	Record<string, string>	{}	Additional headers for API requests
apiParams	Record<string, any>	{}	Additional parameters for API requests
placeholder	string	'Select options...'	Placeholder text for the input
label	string	-	Label for the dropdown
required	boolean	false	Whether the field is required
disabled	boolean	false	Whether the dropdown is disabled
className	string	''	Additional CSS classes
searchEnabled	boolean	true	Enable search functionality
searchPlaceholder	string	-	Placeholder for search input
minSearchLength	number	0	Minimum characters before triggering search
allowAddNew	boolean	true	Allow adding new options
addNewPrefix	string	'Add new: '	Prefix for new option suggestions
onAddNew	(value: string) => Promise<Option | null>	-	Callback for adding new options
multiple	boolean	true	Enable multi-selection
maxSelections	number	-	Maximum number of selections allowed
onChange	(selectedOptions: Option[]) => void	-	Callback when selection changes
onSearch	(searchTerm: string) => void	-	Callback when search term changes
onBlur	() => void	-	Callback when input loses focus
onFocus	() => void	-	Callback when input gains focus
value	Option[]	[]	Controlled value
defaultValue	Option[]	[]	Default value
clearButton	boolean	true	Show clear button
size	'sm' | 'md' | 'lg'	'md'	Size of the dropdown
error	string	-	Error message to display
touched	boolean	false	Whether the field has been touched

Types

Option

interface Option {
  id: string | number;
  label: string;
  [key: string]: any;
}

ApiResponse

interface ApiResponse<T> {
  data: T[];
  total?: number;
  page?: number;
  limit?: number;
  [key: string]: any;
}

API Response Format

The component expects the API to return data in one of these formats:

Array Format

[
  { "id": 1, "label": "Option 1" },
  { "id": 2, "label": "Option 2" }
]

Object Format

{
  "data": [
    { "id": 1, "label": "Option 1" },
    { "id": 2, "label": "Option 2" }
  ],
  "total": 2,
  "page": 1,
  "limit": 10
}

Styling

The component uses Bootstrap classes by default. You can customize the styling by:

• Overriding CSS classes
• Using the className prop
• Customizing the Bootstrap theme

Custom CSS Example

.multi-selector-dropdown .rbt-input-main {
  border-radius: 0.375rem;
}

.multi-selector-dropdown .btn-outline {
  border-radius: 50px;
}

.multi-selector-dropdown .checkbox-pill {
  background-color: #007bff;
  border-color: #007bff;
}

Error Handling

The component includes built-in error handling for:

• API request failures
• Network errors
• Invalid responses
• Add new option failures

Errors are logged to the console and can be handled through the onAddNew callback.

Accessibility

The component is built with accessibility in mind:

• Proper ARIA labels
• Keyboard navigation support
• Screen reader compatibility
• Focus management

Browser Support

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

Testing

The component includes comprehensive tests:

npm test

All tests are passing and cover:

• Component rendering
• API integration
• Search functionality
• Add new option feature
• Multi-selection behavior
• Error handling

Development

Local Testing

# Build the package
npm run build

# Run tests
npm test

# Link for local development
npm link

Publishing

# Build and publish
npm run build
npm publish

License

MIT

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Submit a pull request

💡 Contributing

Pull requests and issues are welcome! Please open an issue or PR on GitHub.

👤 Author

Akshay Bhalala
[e-mail]

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔑 Keywords

• react
• dropdown
• multi-select
• typeahead
• search
• api
• typescript
• bootstrap
• form-control
• autocomplete
• select
• input
• ui-component
• react-component
• javascript
• frontend
• web-development
• user-interface
• interactive
• responsive