Edit this page
[?] Component size, gzipped: 184kb

Select

The select and search controls allow the user to select an option or options.

Select menus in Base hover atop of a selection menu while providing a simple list of options. Proper spacing, color, and a check-mark are clear indicators of a selection. Each menu is scrollable, if applicable.

Examples

Select basic usage

Things to note in the example source code:

  • the value is always an Array to provide a consistent interface - no matter if you use multi or single selects,
  • you have to call setState with the entire object, not just the id value.

When type is 'search' a magnifying glass icon will be rendered to the input's left and a dropdown arrow will not be rendered to the right.

Select with custom labels

Select creatable

The creatable select enables users to create new options along with choosing existing options.

Select creatable multi-pick

Select sizes



Select similar to native select

Select uncontrolled example

Select with many options

Select in a modal dialog

Select with open dropdown

Select...
open

Use startOpen to mount the Select with an open dropdown. Combine this with autoFocus if you want the input to be focused as well. Note, the dropdown will close once an item is selected or if the escape key is pressed while the Select has focus. If you want the dropdown to stay open you might be better off using Menu directly.

Select with overridden menu

Select dropdown overrides

To override the Popover that's being used by the Dropdown subcomponent, you have to use a nested override.

Overrides

Additionally, you can fully customize any part of the Select through the overrides prop. The Select consists of multiple subcomponents that are listed bellow and you can override each one of them. To help you identify the names of these subcomponents, you can highlight them through this selector:

Note: You should always use longhand CSS properties. Mixing shorthands and longhands will lead into strange behaviors!

API

Select API

"aria-label" nullable string = null

"aria-describedby" nullable string = null

"aria-labelledby" nullable string = null

autoFocus boolean = false

Defines if select element is focused on the first mount.

backspaceRemoves boolean = true

Defines if options can be removed by pressing backspace.

clearable boolean = true

Defines if the select value can be cleared. If true a clear icon is rendered when a value is set.

closeOnSelect boolean = true

Defines if the menu closes after a selection if made.

creatable boolean = false

Defines if new options can be created along with choosing existing options.

deleteRemoves boolean = true

Defines if options can be removed by pressing backspace.

disabled boolean = false

Defines if the control is disabled.

error boolean = false

Defines if the control is in error state.

positive boolean = false

Defines if the control if in positive state.

escapeClearsValue boolean = true

Defines if the value is cleared when escape is pressed and the dropdown is closed.

filterOptions nullable function = (options, filterValue, excludeOptions, newProps) => undefined

Defaults to filterOptions that excludes selected options for multi select. A custom method to filter options to be displayed in the dropdown.

function
$ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
,
string,
$ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
,
valueKey string required
labelKey string required
=> $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean

filterOutSelected boolean = true

Defines if currently selected options are filtered out in the dropdown options.

getOptionLabel nullable function = null

A custom method to get a display value for a dropdown option.

option required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
optionState object required
$selected boolean required
$disabled boolean required
$isHighlighted boolean required
=> Node

getValueLabel nullable function = null

A custom method to get a display value for a selected option.

option required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
=> Node

id string

Sets the id attribute of the internal input element. Allows for usage with labels.

isLoading boolean = false

Defines if the select if in a loading (async) state.

labelKey string = "label"

Defines an option key for a default label value.

maxDropdownHeight string = "900px"

Sets max height of the dropdown list.

multi boolean = false

Defines if multiple options can be selected.

noResultsMsg Node

Message to be displayed if no options is found for a search query.

Node

onBlur function = () => undefined

Event => mixed

onBlurResetsInput boolean = true

Defines if the input value is reset to an empty string when a blur event happens on the select.

onChange function = () => undefined

change handler of the select to be called when a value is changed.

value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
option nullable required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
type required $KeysObject.freeze({ select: "select", remove: "remove", clear: "clear" })
 => mixed

onFocus function = () => undefined

SyntheticEventHTMLElement => mixed

onInputChange function = () => undefined

SyntheticInputEventHTMLInputElement => mixed

onCloseResetsInput boolean = true

Defines if the input value is reset to an empty string when dropdown is closed.

onSelectResetsInput boolean = true

Defines if the input value is reset to an empty string when a selection is made.

onOpen nullable function = null

A function that is called when the dropdown opens.

() => mixed

onClose nullable function = null

A function that is called when the dropdown closes.

() => mixed

openOnClick boolean = true

Defines if the dropdown opens on a click event on the select.

startOpen boolean = false

If true, opens the dropdown when the select mounts.

options nullable $ReadOnlyArray<$ReadOnly<object>> = []

Options to be displayed in the dropdown. If an option has a disabled prop value set to true it will be rendered as a disabled option in the dropdown.

$ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean

overrides object = {}

Root { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ControlContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Placeholder { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ValueContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SingleValue { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
MultiValue { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
InputContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Input { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
IconsContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SelectArrow { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ClearIcon { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
LoadingIndicator { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SearchIcon { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Popover { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Dropdown { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownOption { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownListItem { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
OptionContent { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
StatefulMenu { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*

placeholder Node

Sets the placeholder.

Node

required boolean = false

Defines if the select field is required to have a selection.

searchable boolean = true

Defines if the search functionality is enabled.

size $Keys<typeof SIZE> =

Defines the size (scale) of dropdown menu items. See the Menu component API.

$Keys{ default: "default", compact: "compact", large: "large" }

type $Keys<typeof TYPE> =

Defines type of the component to be in select or search mode. When set to TYPE.search the search icon if rendered on the left and the select arrow icon is not rendered.

$Keys{ select: "select", search: "search" }

value $ReadOnlyArray<$ReadOnly<object>> = []

A current selected value(s). If a selected value has a clearableValue prop set to true it will be rendered as a disabled selected option that can't be cleared.

$ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean

valueKey string = "id"

Defines a key name for an option's unique identifier value. The value of the valueKey prop is used to identify what options are selected or removed from the selection, it also used for default filtering out the selected options from the dropdown list.

mountNode HTMLElement

Where to mount the popover

HTMLElement

StatefulSelectContainer API

overrides object = {}

Root { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ControlContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Placeholder { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ValueContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SingleValue { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
MultiValue { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
InputContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Input { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
IconsContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SelectArrow { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ClearIcon { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
LoadingIndicator { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SearchIcon { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Popover { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Dropdown { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownOption { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownListItem { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
OptionContent { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
StatefulMenu { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*

children function required

"aria-label" nullable required string
"aria-describedby" nullable required string
"aria-labelledby" nullable required string
autoFocus boolean required
backspaceRemoves boolean required
clearable boolean required
closeOnSelect boolean required
creatable boolean required
deleteRemoves boolean required
disabled boolean required
error boolean required
positive boolean required
escapeClearsValue boolean required
filterOptions nullable required function
$ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
,
string,
$ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
,
valueKey string required
labelKey string required
=> $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
filterOutSelected boolean required
getOptionLabel nullable required
option required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
optionState object required
$selected boolean required
$disabled boolean required
$isHighlighted boolean required
=> Node
getValueLabel nullable required
option required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
=> Node
id string
isLoading boolean required
labelKey string required
maxDropdownHeight string required
multi boolean required
noResultsMsg Node
onBlur function required Event => mixed
onBlurResetsInput boolean required
onChange function required
value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
option nullable required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
type required $KeysObject.freeze({ select: "select", remove: "remove", clear: "clear" })
 => mixed
onFocus function required SyntheticEventHTMLElement => mixed
onInputChange function required SyntheticInputEventHTMLInputElement => mixed
onCloseResetsInput boolean required
onSelectResetsInput boolean required
onOpen nullable required () => mixed
onClose nullable required () => mixed
openOnClick boolean required
startOpen boolean required
options nullable required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
overrides required
Root { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ControlContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Placeholder { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ValueContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SingleValue { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
MultiValue { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
InputContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Input { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
IconsContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SelectArrow { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ClearIcon { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
LoadingIndicator { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
SearchIcon { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Popover { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownContainer { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Dropdown { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownOption { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
DropdownListItem { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
OptionContent { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
StatefulMenu { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
placeholder Node
required boolean required
searchable boolean required
size required $Keys{ default: "default", compact: "compact", large: "large" }
type required $Keys{ select: "select", search: "search" }
value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
valueKey string required
mountNode HTMLElement
 => React$Node

initialState object = { value: [] }

value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean

stateReducer function = (type, nextState) => undefined

function
string,
value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
,
value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
=>
value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean

onChange function = () => undefined

value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
option nullable required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
type required $KeysObject.freeze({ select: "select", remove: "remove", clear: "clear" })
 => mixed

Select exports

You can import this module like so:

import {Select} from 'baseui/select'

It exports the following components or utility functions:

  • Select
  • SingleValue
  • MultiValue
  • AutosizeInput
  • SelectDropdown
  • StatefulSelect
  • StatefulSelectContainer
  • StyledRoot
  • StyledControlContainer
  • StyledValueContainer
  • StyledPlaceholder
  • StyledSingleValue
  • StyledInputContainer
  • StyledInput
  • StyledInputSizer
  • StyledIconsContainer
  • StyledSelectArrow
  • StyledClearIcon
  • StyledSearchIcon
  • StyledDropdownContainer
  • StyledDropdown
  • StyledDropdownListItem
  • StyledOptionContent
  • filterOptions
  • SIZE
  • TYPE
  • STATE_CHANGE_TYPE