react-bs-searchable-select

A flexible, searchable dropdown select component for React with Bootstrap styling. Supports filtering, custom values, imperative methods, and full styling customization.

Features

• Search & Filter — Type to filter options (case-insensitive, matches anywhere in label)
• Custom Values — Optionally allow users to enter values not in the list
• Clearable — One-click clear button with optional disable
• Imperative API — Programmatically get/set values, add/remove options via ref
• Styling — Inline color props, CSS class overrides, or automatic Bootstrap theme integration
• Validation — Built-in isInvalid prop for Bootstrap form validation

Installation

npm install react-bs-searchable-select

Peer Dependencies

This component requires the following packages (typically already in a React + Bootstrap project):

npm install react react-dom react-bootstrap react-icons

Quick Start

import { useState } from 'react';
import SearchableSelect from 'react-bs-searchable-select';

function App() {
  const [value, setValue] = useState(null);

  const options = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
  ];

  return (
    <SearchableSelect
      options={options}
      value={value}
      onChange={(val) => setValue(val)}
      placeholder="Select a fruit..."
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | options | Array<{ value: any, label: string }> | [] | Array of selectable options | | value | any | — | Currently selected value (controlled) | | onChange | (value, option) => void | — | Called on selection change; receives (null, null) when cleared | | placeholder | string | 'Select...' | Placeholder text | | maxDropdownHeight | number | 200 | Max dropdown height in pixels | | allowCustomValue | boolean | false | Allow values not in the options list | | isDisabled | boolean | false | Disable the component | | isClearable | boolean | true | Show/hide the clear (×) button | | isInvalid | boolean | false | Apply Bootstrap invalid styling | | activeBackgroundColor | string | var(--bs-primary, #0d6efd) | Background color of the selected item | | activeTextColor | string | #fff | Text color of the selected item | | activeClassName | string | — | CSS class for the selected item (overrides inline styles) | | inactiveBackgroundColor | string | — | Background color for unselected items | | inactiveTextColor | string | — | Text color for unselected items | | inactiveClassName | string | — | CSS class for unselected items (overrides inline styles) |

Imperative Methods

Access methods via a React ref:

import { useRef } from 'react';

const selectRef = useRef();

<SearchableSelect ref={selectRef} options={options} value={value} onChange={setValue} />

selectRef.current.setValue('apple');       // Select a value programmatically
selectRef.current.getValue();              // Get current value (selected or custom)
selectRef.current.isCustomValue();         // true if the value is custom text
selectRef.current.getInputText();          // Get raw input text
selectRef.current.clearSelection();        // Clear the selection
selectRef.current.addOption({ value: 'new', label: 'New Option' });  // Add option
selectRef.current.removeOption('apple');   // Remove option by value

| Method | Returns | Description | |--------|---------|-------------| | setValue(value) | void | Select a value from options (or set custom if allowCustomValue) | | getValue() | any | Returns selected value or custom text | | isCustomValue() | boolean | true if the value is not from the options list | | getInputText() | string | Returns current raw input text | | clearSelection() | void | Clears the selection | | addOption(option) | void | Adds { value, label } to options (ignores duplicates) | | removeOption(value) | void | Removes an option; clears selection if it was active |

Examples

Custom Values

const selectRef = useRef();

<SearchableSelect
  ref={selectRef}
  options={options}
  value={value}
  onChange={(val) => setValue(val)}
  allowCustomValue
  placeholder="Select or type a custom value..."
/>

// On form submit:
const currentValue = selectRef.current.getValue();
const isCustom = selectRef.current.isCustomValue();

Styling with Inline Colors

<SearchableSelect
  options={options}
  value={value}
  onChange={setValue}
  activeBackgroundColor="#28a745"
  activeTextColor="#fff"
  inactiveBackgroundColor="#f8f9fa"
  inactiveTextColor="#333"
/>

Styling with CSS Classes

<SearchableSelect
  options={options}
  value={value}
  onChange={setValue}
  activeClassName="my-active-item"
  inactiveClassName="my-inactive-item"
/>

.my-active-item {
  background-color: #6f42c1 !important;
  color: #fff !important;
  border-left: 3px solid #4a2a8a;
}
.my-inactive-item:hover {
  background-color: #e9ecef;
}

Form Validation

<SearchableSelect
  options={options}
  value={value}
  onChange={setValue}
  isInvalid={!!errors.field}
/>
{errors.field && (
  <Form.Control.Feedback type="invalid" style={{ display: 'block' }}>
    {errors.field}
  </Form.Control.Feedback>
)}

Non-Clearable Select

<SearchableSelect
  options={options}
  value={value}
  onChange={setValue}
  isClearable={false}
/>

Disabled State

<SearchableSelect
  options={options}
  value={value}
  onChange={setValue}
  isDisabled
/>

Bootstrap Theme Integration

The active item uses Bootstrap's primary color via CSS variable by default:

var(--bs-primary, #0d6efd)

If you customize $primary in your Bootstrap SCSS, the component picks it up automatically. No --bs-primary? It falls back to Bootstrap's default blue.

License

MIT © Hussein Al Bayati