SelectMultiple

a control to select multiple values, with optional inline display

Using Grommet for HPE?See SelectMultiple 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 }) => {}

defaultValue

Initially selected value.

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

help

Optional help text to display above the options in the drop.

string

help text

node

<Box background='gray'> help text </Box>

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.

() => {}

limit

The maximum number of options that can be selected.

number

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.

To affect all SelectMultiple instances, use messages prop on Grommet.

object

{ multiple: "string" }

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 SelectMultiple 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. When 'onMore' is defined the 'Select All' button is removed from the SelectMultiple.

() => {}

onOpen

Function that will be called when the SelectMultiple 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. If the 'onMore' prop is being used and the 'options' prop doesn't reflect all the potential options, the 'onSearch' function supports modifying the 'options' based on a search term.

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 SelectMultiple 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>

showSelectedInline

Whether selections should be displayed at the input level of the component.

boolean

true

false

size

The size of the text and icon.

string

"small"

"medium"

"large"

"xlarge"

"string"

sortSelectedOnClose

Whether selections should be sorted with selected items displayed at the top of the list after closing and reopening the drop. Note: code that relies on indexes of the options shouldn't be used when sortSelectedOnClose is true.

boolean

true

false

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 more of the options from the options array.

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

selectMultiple.maxInline

The maximum number of items to display at the input level when showSelectedInline is true.

number

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