Configuration | react-searchable-dropdown

Overview

Both components share a common set of props for search, filtering, positioning, and styling. The only difference is how selection state is managed: single select uses value/setValue, multi select uses values/setValues plus a few extra props for chip behavior.

Common props

Shared by both components

Prop	Type	Default	Description
`options` *	`T[]`	—	Array of options. Can be strings or objects with label/value.
`placeholder`	`string`	—	Placeholder text shown in the search input.
`disabled`	`boolean`	false	Disables the dropdown.
`debounceDelay`	`number`	0	Milliseconds to debounce the search filter.
`searchOptionKeys`	`Array<keyof T>`	["label"]	Keys to search against when options are objects. Defaults to ["label"] for object options. Pass additional keys to search more fields.
`filterType`	`TSearchableDropdownFilterType`	CONTAINS	Match strategy used by match-sorter. See Filtering docs.
`dropdownOptionsHeight`	`number`	300	Max height of the dropdown options list in pixels.
`createNewOptionIfNoMatch`	`boolean`	true	Whether to show a 'create new' option when no matches are found.
`dropdownOptionNoMatchLabel`	`string`	No Match	Label shown for the no-match / create-new option.
`dropdownNoOptionsLabel`	`string`	—	Label shown when the options array is empty.
`offset`	`number`	5	Pixel gap between the input and the dropdown list.
`strategy`	`'absolute' \| 'fixed'`	absolute	CSS positioning strategy for the dropdown portal.
`DropdownIcon`	`ComponentType<{ toggled: boolean }>`	—	Custom icon component for the dropdown toggle.
`searchQuery`	`string \| undefined`	—	Controlled search query value. Makes the search input controlled.
`onSearchQueryChange`	`(query: string \| undefined) => void`	—	Callback when the search query changes. Pair with searchQuery for controlled mode.
`onBlur`	`() => void`	—	Callback when the dropdown loses focus.

Single select props

SearchableDropdown specific

Prop	Type	Default	Description
`value` *	`T \| undefined`	—	The currently selected option.
`setValue` *	`(option: T) => void`	—	Callback when an option is selected.

Multi select props

SearchableDropdownMulti specific

Prop	Type	Default	Description
`values` *	`T[] \| undefined`	—	Array of currently selected options.
`setValues` *	`(options: T[]) => void`	—	Callback when the selection changes.
`deleteLastChipOnBackspace`	`boolean`	false	Remove the last selected chip when pressing backspace on an empty search input.
`onClearAll`	`() => void`	—	Callback when the clear all button is clicked.
`onClearOption`	`(option: T) => void`	—	Callback when an individual chip is removed.
`ClearAllIcon`	`ComponentType`	—	Custom icon for the clear all button.

Grouping props

Group support (both components)

Prop	Type	Default	Description
`handleGroups`	`(matchingOptions: T[]) => { groupCounts: number[]; groupCategories: string[] }`	—	Function that computes group boundaries from the current filtered options.
`groupContent`	`(index: number, groupCategories: string[], context: G) => ReactNode`	—	Render function for group headers.
`context`	`G`	—	Arbitrary data passed through to groupContent. Useful for passing callbacks or config.

CSS class props

Styling overrides

Prop	Type	Default	Description
`classNameSearchableDropdownContainer`	`string`	—	Root container element.
`classNameSearchQueryInput`	`string`	—	The search input field.
`classNameDropdownOptions`	`string`	—	The dropdown options container.
`classNameDropdownOption`	`string`	—	Individual option items.
`classNameDropdownOptionFocused`	`string`	—	The currently focused (keyboard-navigated) option.
`classNameDropdownOptionSelected`	`string`	—	The currently selected option (single select only).
`classNameDropdownOptionDisabled`	`string`	—	Disabled options.
`classNameDropdownOptionLabel`	`string`	—	The text label inside each option.
`classNameDropdownOptionLabelFocused`	`string`	—	The text label of the focused option.
`classNameDropdownOptionNoMatch`	`string`	—	The no-match / create-new option.
`classNameTriggerIcon`	`string`	—	The dropdown toggle icon.
`classNameTriggerIconInvert`	`string`	—	The icon when the dropdown is open (rotated state).
`classNameDisabled`	`string`	—	Applied to the container when disabled.
`inputId`	`string`	—	HTML id attribute for the search input. Useful for label association.

Multi select has three additional class props: classNameMultiSelectedOption, classNameMultiSelectedOptionClose, and classNameClearAll.

Next steps

Filtering — understand match strategies and debouncing
Styling — theming with CSS classes and variables
API Reference — full export list and type definitions