Select

a control to select a value, with optional search

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string
"a user friendly label for screen readers"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string
"start"
"center"
"end"
"stretch"

children

Function that will be called when each option is rendered.

function

The function will be passed (option, index, options, state) where option is the option to render, index is the index of that option in the options array, and state is an object with (active, disabled, selected) keys indicating the current state of the option.

(option, index, options, { active, disabled, selected }) => {}

clear

Whether to provide a button option to clear selections.

boolean
true
false
object

{
  position: "top" | "bottom",
  label: "string"
}
            

closeOnChange

Wether to close the drop when a selection is made.

boolean
true
false

defaultValue

Initially selected value. This can be an array when multiple.

string
"value1"
object
{}
number
1
array

An array of strings, objects, or numbers.

["string", ...]
[{...}, {...}]
[1, 2]

disabled

Whether the entire select or individual options should be disabled.

boolean
true
false
array

An array of strings, objects, or numbers. An array of numbers indicates the indexes into 'options' of the disabled options. An array of strings or objects work the same way as the 'value' to indicate which options are disabled.

["string", ...]
[{...}, {...}]
[1, 2]

disabledKey

When the options array contains objects, this property indicates how to determine which options should be disabled.

string

If a string is provided, it is used as the key for each item object and if that key returns truthy, the option is disabled.

"key"
function

If a function is provided, it is called with the option and the return value determines if the option is disabled.

() => {}

dropAlign

How to align the drop.

object

{
  top: "top" | "bottom",
  bottom: "top" | "bottom",
  right: "left" | "right",
  left: "left" | "right"
}
            
{ top: "bottom", left: "left" }

dropHeight

The height of the drop container.

string
"xsmall"
"small"
"medium"
"large"
"xlarge"
"string"

dropProps

Any valid Drop prop.

object
{}

dropTarget

Target where the options drop will be aligned to. This should be a React reference. Typically, this is not required as the drop will be aligned to the Select itself by default.

object
ref.current

emptySearchMessage

Empty option message to display when no matching results were found

string
"No matches found"

focusIndicator

Whether when 'plain' it should receive a focus outline.

boolean
true
false

gridArea

The name of the area to place this inside a parent Grid.

string
"a parent grid area name"

icon

A custom icon to be used when rendering the select. You can use false to not render an icon at all.

boolean
true
false
function
() => {}
node
<Icon />

labelKey

When the options array contains objects, this property indicates how to retrieve the label for each option. The label is what is displayed to the user in the options list drop down and for the selected option itself.

string

If a string is provided, it is used as the key to retrieve a property of an option object, which should be a string.

"key"
function

If a function is provided, it is called with the option and should return a string or a React node.

() => {}

margin

The amount of margin around the component.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}
        

messages

Custom messages.

object
{ multiple: "string" }

multiple

Whether to allow multiple options to be selected. When multiple is true, 'value' should be an array of selected options and 'options' should be an array of possible options.

boolean
true
false

name

The name of the attribute when in a Form or FormField.

string
"name"

onChange

Function that will be called when the user selects an option.

function
({ value, option }) => {...}

onClose

Function that will be called when the Select drop closes.

function
() => {}

onMore

Use this to indicate that 'items' doesn't contain all that it could.

function

The function will be called when the entire list of items has been rendered. This might be used when the total number of items that could be retrieved is more than you'd want to load into the browser. 'onMore' allows you to lazily fetch more from the server only when needed.

() => {}

onOpen

Function that will be called when the Select drop opens.

function
() => {}

onSearch

Function that will be called when the user types in the search input. If this property is not provided, no search field will be rendered.

function
() => {}

open

The control for the open and close state of the component.

boolean
true
false

options

The options to choose from.

array[string]
["option1", "option2"]
array[number]
[1, 2]
array[boolean]
[true, false]
array[element]
[<Element />, <Element />]
array[object]

If an object is used, use children callback in order to render anything based on the current item.

[{}, {}]

placeholder

Placeholder to use when no value is provided.

string
"placeholder"
element
<Element />
node
{}

plain

Whether this is a plain Select input with no border or padding.

boolean
true
false

replace

Whether to replace previously rendered items with a generic spacing element when they have scrolled out of view. This is more performant but means that in-page searching will not find elements that have been replaced.

boolean
true
false

searchPlaceholder

Placeholder text to use in the search box when the search input is empty.

string
"search..."

selected

Index of the currently selected option. When multiple, the set of options selected. NOTE: This is deprecated in favor of indicating the selected values via the 'value' property.

number
1
array[number]
[1, 2]

size

The size of the text and icon.

string
"small"
"medium"
"large"
"xlarge"
"string"

value

The currently selected value. When 'valueKey' sets 'reduce', the value(s) here should match what the 'valueKey' would return for the corresponding selected option object. Otherwise, the value should be one (or multiple, when multiple = true) of the options from the options array.

string
"option1"
element

Passing an element allows the caller to control how the value is rendered. Passing an element is deprecated. Instead, use the 'valueLabel' property.

<Element />
object
{}
number
1
array[string]
["option1", "option2"]
array[number]
[1, 2]
array[object]
[{}, {}]

valueKey

When the options array contains objects, this property indicates how to retrieve the value of each option.

string

If a string is provided, it is used as the key to retrieve a property of an option object.

"key"
function

If a function is provided, it is called with the option and should return the value. If reduce is true, this value will be used for the 'value' delivered via 'onChange'.


{
  key: "string",
  reduce: boolean
}
            

valueLabel

Provides custom rendering of the value. If not provided, Select will render the value automatically.

node
<Box>...</Box>

Theme

global.hover.background

The background style when hovering.

string
"active"
object
{ color: "active", opacity: "medium" }

global.hover.color

The text color when hovering.

string

A hex, name, or rgb value.

"black"
object

An object with a color for dark and light modes.

{ dark: "white", light: "black" }

select.background

The background color used for Select.

string
"white"

select.options.container

Any valid Box prop for the options container.

object
{ align: "start", pad: "small" }

select.options.text

Any valid Text prop for text used inside the options container.

object
{ margin: "none" }

select.container.extend

Any additional style for the container of the Select component.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

select.clear.container

Any valid Box prop for the clear button container.

object
{ pad: "small", background: "light-2" }

select.clear.text

Any valid Text prop for text used inside the clear button container.

object
{ color: "dark-3" }

select.control.open

Any additional style for the Select DropButton when using the controlled open state.

string
"CSS"
object
{}

select.control.extend

Any additional style for the control of the Select component.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

select.icons.margin

The margin used for Select icons.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}
        

select.icons.color

The color used for Select icons.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

select.icons.down

The down icon to use for opening the Select.

element
<FormDown />

select.icons.up

The up icon to use for closing the Select.

element
<FormUp />

select.searchInput

Component for the Select search input field.

React.Component
<Component />

select.step

How many items to render at a time.

number
 20