Multi select

Multi select presents user with a set of options and allows to select many of them.

Always pair a multi select with a form field label so the control is named for everyone, including screen reader users.

#Usage

#Disabled

Select should be disabled, when user shouldn't be allowed to interact with it.

Individual options can be disabled too.

You can also provide a custom message when an option is disabled:

#Loading

Mark select as loading, when options are fetched on the fly and are not yet available.

#Invalid

Invalid select indicates that current value isn't what the system expects.

#Clearable

Clearable select should be used when empty selection is acceptable.

#Description

Options can display an additional descriptive text underneath the label.

#Accessories

Options can display an additional accessory view before the label. You can show an image using an image accessory. This is useful for showing logos when selecting sources or destinations, for example.

Icons can be accessories too.

#Custom objects

You don't have to create objects with label and value keys as shown in the examples above. MultiSelect supports any objects, as long as you provide a label and value for each option via optionLabel and optionValue functions. description may be replaced with the optionDescription function.

#Groups

There's a version of MultiSelect called GroupedMultiSelect, that supports groups of options.

#Medium font weight

Use fontWeight="medium" to emphasize the multi select when in views with many selects or in-line with text; it combines with any variant.

#Alternative variant

Use the alternative variant to deemphasize the multi select when there are many selects.

#Tertiary variant

Use the tertiary variant when using the select inside another component.

#Size

The size prop impacts font-size and height. Default is set to md.

To set the width, use the width prop instead.

#Popover width

When rendering smaller-width selects, you may end up with options that are quite tall. To make the options easier to read, pass in a specific width for the popover using popoverWidth.

It is recommended to match widths, when possible.

#Header

Show a header section within the select when the options are displayed.

#Guidelines

#When to use

• When user should be able to select multiple options at once.

#When not to use

• When user should be able to select only one option.
• When user should be able to create new options on the fly.

#Content

• Use sentence case for tab titles.

#Props

#MultiSelect

Name	Default	Description
headerLabel	—	stringShow a header label at the top when displaying the options.
headerDescription	—	stringShow a header description at the top when displaying the options.
isDisabled	—	booleanDetermines if select is disabled.
isLoading	—	booleanIndicates that options are being loaded.
isInvalid	—	booleanIndicates that select is in invalid state.
isClearable	false	booleanDetermines if selection can be cleared.
isOptionDisabled	—	(option: Option) => boolean | stringFunction to determine whether an option should be disabled. If a string is returned, it will be used as a disabled message.
emptyOptionsMessage	"No options"	stringText to show inside a dropdown when there are no options.
options	—	Option[]Available options. Option is a generic, so type of options will be inferred.
optionLabel	—	(option: Option) => stringFunction to extract label from an option. If it's not provided, label field will be used as a label.
optionDescription	—	(option: Option) => stringFunction to extract description from an option. If it's not provided, description field will be used as a label.
optionValue	—	(option: Option) => OptionValueFunction to extract value from an option. If it's not provided, value field will be used as a value.
optionAccessories	—	IconAccessoriesGetter<Option>Function to show an accessory view near the option label.
placeholder	—	stringPlaceholder text to show inside a select when nothing is selected.
removePortal	false	booleanDetermines if the select dropdown should be rendered in a portal.
variant	"default"	"default" | "alternative" | "tertiary"Determines the appearance of the multi select.
fontWeight	"normal"	"normal" | "medium"Determines the font weight of the value and placeholder text.
size	"md"	"sm" | "md" | "lg"Select size.
value	—	OptionValue[]Selected options.
width	"xs"	"xs" | "sm" | "md" | "lg" | "xl" | "auto" | "100%"Select width.
popoverWidth	undefined	"xs" | "sm" | "md" | "lg" | "xl"The dropdown width. If not provided, the select width will be used.
onChange	—	(value: OptionValue[]) => voidCallback for when user selects a different option or clears the selection.
onClose	—	() => voidCallback for when user closes the select.
onOpen	—	() => voidCallback for when user opens the select.
valueLabel	—	(option: Option) => stringFunction to format a selected option's label. If not provided, label field will be used as a label.
selectRef	—	RefObject<HTMLButtonElement>Reference to the select element.

#GroupedMultiSelect

Name	Default	Description
isDisabled	—	booleanDetermines if select is disabled.
isLoading	—	booleanIndicates that options are being loaded.
isInvalid	—	booleanIndicates that select is in invalid state.
isClearable	false	booleanDetermines if selection can be cleared.
isOptionDisabled	—	(option: Option) => boolean | stringFunction to determine whether an option should be disabled. If a string is returned, it will be used as a disabled message.
emptyOptionsMessage	"No options"	stringText to show inside a dropdown when there are no options.
optionGroups	—	Array<{ label: string; options: Option[]; }>Available options. Option is a generic, so type of options will be inferred.
optionLabel	—	(option: Option) => stringFunction to extract label from an option. If it's not provided, label field will be used as a label.
optionDescription	—	(option: Option) => stringFunction to extract description from an option. If it's not provided, description field will be used as a label.
optionValue	—	(option: Option) => OptionValueFunction to extract value from an option. If it's not provided, value field will be used as a value.
optionAccessories	—	IconAccessoriesGetter<Option>Function to show accessory views near the option label.
placeholder	—	stringPlaceholder text to show inside a select when nothing is selected.
removePortal	false	booleanDetermines if the select dropdown should be rendered in a portal.
variant	"default"	"default" | "alternative" | "tertiary"Determines the appearance of the grouped multi select.
fontWeight	"normal"	"normal" | "medium"Determines the font weight of the value and placeholder text.
size	"md"	"sm" | "md" | "lg"Select size.
value	—	OptionValue[]Selected options.
width	"xs"	"xs" | "sm" | "md" | "lg" | "xl" | "auto" | "100%"Select width.
popoverWidth	undefined	"4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg"The dropdown width. If not provided, the select width will be used.
onChange	—	(value: OptionValue[]) => voidCallback for when user selects a different option or clears the selection.
valueLabel	—	(option: Option) => stringFunction to format a selected option's label. If not provided, label field will be used as a label.
selectRef	—	RefObject<HTMLButtonElement>Ref to the select element.