React Searchable Dropdown VIEW DEMO

A modern, accessible, and customizable dropdown component for React applications.

I created this library because I was tired of piecing together different dropdown components to get the features I needed. You know the drill - one library has virtualization but looks terrible, another looks great but can't handle large lists, and yet another has a nice API but no way to create new options.

What I really wanted was a dropdown that:

• Handles large lists smoothly (virtualization)
• Lets users create new options when they don't find what they're looking for
• Looks good out of the box but is easy to style to match your project
• Works with both simple string arrays and complex object arrays - no data transformation needed

The good news? I built it! This library combines these essential features in a way that:

• Works great right away with sensible defaults
• Needs minimal setup for most cases
• Styling is a breeze - just add your CSS classes
• All the good stuff in one package, no more mixing and matching

• 🔍 Real-time search filtering
• ⌨️ Keyboard navigation support
• 🌐 Portal rendering for overflow handling
• 🔄 Smart positioning handling scrolling and flipping
• 🎯 Single and multi-select variants
• 📦 Optionally grouped dropdown options
• 🎨 Fully customizable styling
• 🚀 Virtualized list for performance
• ✨ Create new options on the fly
• ♿ Accessibility support
• 🎭 Custom icons support
• 🔒 Disabled state support

npm install @luciodale/react-searchable-dropdown
# or
yarn add @luciodale/react-searchable-dropdown
# or
bun add @luciodale/react-searchable-dropdown

The components support two types of options:

1. String Array - Simple array of strings:

const options = ['Option 1', 'Option 2', 'Option 3'];

2. Object Array - Array of objects with required label and value properties, plus optional metadata:

const options = [
  { 
    label: 'Option 1', 
    value: '1',
    description: 'This is option 1',
    category: 'A',
    // ... any other metadata
  },
  { 
    label: 'Option 2', 
    value: '2',
    description: 'This is option 2',
    category: 'B',
    // ... any other metadata
  }
];

Important: When using object options, you must specify the searchOptionKeys prop to define which fields should be used for filtering. This is a required prop for object options.

<SearchableDropdown
  options={options}
  searchOptionKeys={['label']} // Required for object options
  // ... other props
/>

The searchOptionKeys array tells the component which fields to search through when filtering options. For example, with the above configuration, searching for "A" would match options where solely the label contains "A".

import { SearchableDropdown } from '@luciodale/react-searchable-dropdown';
import "@luciodale/react-searchable-dropdown/dist/assets/single-style.css";


const options = [
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' },
  // ...
];

function MyComponent() {
  const [value, setValue] = useState<{label: string, value: string}>(options[0]);

  return (
    <SearchableDropdown
      options={options}
      value={value}
      setValue={setValue}
      placeholder="Select an option..."
      searchOptionKeys={['label']}
    />
  );
}

import { SearchableDropdownMulti } from '@luciodale/react-searchable-dropdown';
import "@luciodale/react-searchable-dropdown/dist/assets/multi-style.css";


const options = [
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' },
  // ...
];

function MyComponent() {
  const [values, setValues] = useState([]);

  return (
    <SearchableDropdownMulti
      options={options}
      values={values}
      setValues={setValues}
      placeholder="Select options..."
      searchOptionKeys={['label']}
    />
  );
}

VIEW THE DEMO for more examples.

Both components share these common props:

The components use Floating UI for positioning and support two key props for customization:

The offset prop controls the distance in pixels between the trigger element and the dropdown. Default is 5.

<SearchableDropdown
  offset={10} // 10px gap between trigger and dropdown
  // ... other props
/>

The strategy prop determines the positioning strategy:

• 'absolute' (default): Positions relative to the nearest positioned ancestor
• 'fixed': Positions relative to the viewport, useful for modals or when breaking out of overflow containers

<SearchableDropdown
  strategy="fixed" // Use fixed positioning
  // ... other props
/>

Both components support extensive styling customization through className props:

<SearchableDropdown
  classNameSearchableDropdownContainer="custom-container"
  classNameSearchQueryInput="custom-input"
  classNameDropdownOptions="custom-options"
  classNameDropdownOption="custom-option"
  classNameDropdownOptionFocused="custom-option-focused"
  classNameDropdownOptionSelected="custom-option-selected"
  classNameDropdownOptionLabel="custom-option-label"
  classNameDropdownOptionLabelFocused="custom-option-label-focused"
  classNameDropdownOptionNoMatch="custom-option-no-match"
  classNameTriggerIcon="custom-trigger-icon"
  classNameTriggerIconInvert="custom-trigger-icon-invert"
  classNameDisabled="custom-disabled"
/>

The multi-select variant includes additional class names for chips:

<SearchableDropdownMulti
  // ... common class names ...
  classNameMultiSelectedOption="custom-chip"
  classNameMultiSelectedOptionClose="custom-chip-close"
  classNameClearAll="custom-clear-all"
/>

This library is in its early versions but has been battle-tested in production environments. While it's solid and reliable, there's always room for improvement! I'm open to:

• New feature ideas
• Performance optimizations
• Better accessibility
• More examples and documentation
• Bug reports and fixes

Feel free to open issues or submit pull requests.

MIT