Select

a control to select a value, with optional search

Storybook

CodeSandbox

Github

Using Grommet for HPE?See Select examples and guidance.

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"

"baseline"

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

Whether 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

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"

node

<Text> No results found. <Text/>

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 'options' 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.

There are a number of ways to set and change the options based on the 'onChange', 'onSelect', and 'onSearch' functions. As a general rule of guidance when using 'onSearch', define an original list of options that is separate from the currently stored options. Use this definition to reset options in functions.

For examples of defining, setting, and changing options, see our Storybook examples with Select.

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..."

node

<Text>Enter search term</Text>

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

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

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"

object

If reduce is true, this value will be used for the 'value' delivered via 'onChange'.


{
  key: "string",
  reduce: boolean
}

function

If a function is provided, it is called with the option and should return the value.

(option) => {}

valueLabel

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

node

<Box>...</Box>

function

A function that returns either a string or a React node.

{(option) => {}}

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.container.hover

Any valid Box prop to adjust the button container style when the clear button is hovered.

object

{}

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.emptySearchMessage.container

Any valid Box props for the emptySearchMessage container.

object

{ pad: "small"}

select.emptySearchMessage.text

Any valid Text props for the emptySearchMessage text.

object

{ color: "text" }

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