Documentation
Select

Select

A dropdown menu input with selection of choices. Options are searchable with fuzzy search.

Select input can have any internal value assigned to each option, with text or custom UI labels. It supports multiple selections and can render large list of options using Virtual List.

Select has Universal Input API, with value format, parse, normalize and event action handlers.

Props

PropTypeDefaultDescription
options
Array
Required

Selectable values

optionProps
Object

Individual option props to pass

optionsProps
Object

Options container props to pass

onChange
Function

Handler(event, value: any, name?, self) when selected value changes

onFocus
Function

Handler(event, value: any, name?: string, self) on select focus

onBlur
Function

Handler(event, value: any, name?: string, self) on select blur

onRemove
Function

Handler(event, value: any, name?: string, self) on input removal.

onChange handler will fire after with null as value, unless event.preventDefault().

To let onChange update form instance first before removing the field,

use setTimeout to execute code inside onRemove handler.

onSearch
Function

Handler(event, query: string, name?, self) when search input value changes

onSelect
Function

Handler(event, value: any, name?, self) when an option gets focus

onClickValue
Function

Handler(event, value: any, name?, self) when a multiple selected value is clicked

onMount
Function

Handler(self: object) when this component has mounted

addOption
Boolean
|
Object
|
Function

Whether to allow users to add new options (in combination with search) Set to true to allow adding new term. Set to object of props to pass to new option object when selected. Set to function(query: string) => boolean | object for conditional logic.

compact
Boolean
|
Number

Whether to use minimal width that fits content, pass number for additional character offset

controlledValue
Boolean

Whether to lock selected value when value prop is given

openInitially
Boolean

Whether to open options initially

excludeSelected
Boolean

Whether to filter out selected value from options dropdown

format
Function

Function(value, name?, self) => any - Serializer for internal Select state value

parse
Function

Function(value, name?, self, event) => any - Deserializer for onChange/onBlur/onFocus value

Select always stores the value or value[] internally for its logic, like fuzzy search

normalize
Function

Function(query, name?, self, event) => string - search query normalizer to sanitize user input

forceRender
Boolean

Whether to always render options, even when closed

icon
String
|
Boolean
|
Object
|
Number
|
Function

Custom Icon name or props to render before input node.

Default is 'dropdown' icon at the end, or 'search' icon at the start if search = true

and icons are undefined or null.

iconEnd
String
|
Boolean
|
Object
|
Number
|
Function

Custom Icon name or props to render after input node

multiple
Boolean

Whether to allow multiple selections and store values as array

fixed
Boolean

Whether to set options with position fixed on open to remain visible inside Scroll

query
String
''

Default search query to use

queryParser
Function

Function(query) => string - parse function for internal query string used for search

search
Boolean
|
Function

Whether to enable search by options, pass Handler(query, options) => value for custom search

searchNonce
Any

Unique ID to trigger search options re-indexing

searchOptions
Object
upward
Boolean

Whether options menu should try to open from the top, default is from the bottom

value
Any

Selected value(s) - if passed, becomes a controlled component

renderSelected
Function

Function(value: any, index: number, array, self) => JSX - to render selected option.

Currently only works for multiple selections.

noOptionsMsg
String
|
Number
|
Boolean
|
Function

Message string to display when there are no options left for multiple select, or

Handler(self) => string - function to render message dynamically (example: using query)

virtualOptionsMinimum
Unsigned Integer
50

Minimum number of Select options to use Virtual List renderer to optimize for performance

Examples

Basic Usage

Example
Via Universal Input
Select Label
Placeholder Text
Expand dropdown options upward

Select Icons

Icon at the start
Icon at the end
Icon at both ends

Select Types

Multiple Choices
Search Selection
Multiple Search Selection
Allow adding new options
Default Search Query

Select Sizes

Example
Compact Selection

Selection Configs

Prefix Selected Option
Selection Suffix
Exclude Selected from Options
Selection with overflowing text
Multiple selections with overflow

Input States

Disabled
Read only
Loading

Input Values

Default Value
Controlled State
Hybrid State (uncontrolled, but updates on `value` changes)
Option `value` different from text label
Custom Options UI

Event Handlers

On Change Callback
On Focus Callback
On Blur Callback

Also refer to Universal Select Input for examples of other selection field props.