MultiSelect

Overview

MultiSelects allow users to select multiple items within a list of options.

When to use:

  • To select multiple options within a list, usually of related or grouped items.
  • To select four or more predefined selections.

Implementation

MultiSelects are typeable inputs with multiple selectable items within a dropdown.

Edit the code below to see your changes live!

function Example() {
const [value, setValue] = useState(['mx']);
const handleChange = (val) => setValue(val);
return (
<Form>
<FormGroup>
<MultiSelect
action={{
actionType: 'destructive' as const,
content: 'Remove Country',
icon: <DeleteIcon />,
onActionClick: () => null,
}}
filterable={true}
label="Countries"
maxHeight={300}
onOptionsChange={handleChange}
options={[
{ value: 'us', content: 'United States' },
{ value: 'mx', content: 'Mexico' },
{ value: 'ca', content: 'Canada' },
{ value: 'en', content: 'England' },
{ value: 'fr', content: 'France' },
{ value: 'gr', content: 'Germany' },
{ value: 'ar', content: 'Argentina' },
{ value: 'ru', content: 'Russia', disabled: true },
{ value: 'ch', content: 'Chile' },
{ value: 'bo', content: 'Bolivia' },
{ value: 'jp', content: 'Japan' },
{ value: 'cn', content: 'China' },
{ value: 'sk', content: 'South Korea' },
{ value: 'au', content: 'Australia' },
{ value: 'ug', content: 'Uganda' },
]}
placeholder="Choose country"
placement="bottom-start"
required
value={value}
/>
</FormGroup>
</Form>
);
}

Props

Prop name
Type
Default
Description
actionSelectAction

Action option displayed at the end of the list.

autoCompletestringoff

Set the autoComplete property for the input.

descriptionstring | FormControlDescription

Append a description to the select field.

disabledbooleanfalse

Disables the MultiSelect component.

errorstring

Displays a form error around the field.

filterablebooleantrue

Allows you to filter the SelectOptions in the MultiSelect.

inputRefReact.Ref<HTMLInputElement> | React.RefObject<HTMLInputElement>

The provided ref will be used for the underlying input element used in the MultiSelect.

labelstring | FormControlLabel

Adds a label to the field.

labelIdstring

Adds a custom id to the label.

maxHeightnumber250

Sets a max-height to the dropdown.

onClose() => void

Function that will be called when the MultiSelect is closed.

onOpen() => void

Function that will be called when the MultiSelect is opened.

onOptionsChange *(value: [any], option: [SelectOption]) => void

Callback called with value of selected option.

options *Array<SelectOption> | Array<SelectOptionGroup>

Accepts an array of SelectOption or an array of SelectOptionGroups. See example for usage.

placementauto-start | auto | auto-end | top-start | top | top-end | right-start | right | right-end | bottom-end | bottom | bottom-start | left-end | left | left-startbottom-start

Determines the location in which the dropdown will be placed.

positionFixedbooleanfalse

If set, uses position: fixed instead of position: absolute to position the items.

requiredboolean

Sets the field as required.

value[any]

Modifies the current selected value of the field.

localization{ optional: string }

Overrides the label with localized text.

Props ending with * are required

Do's and Don'ts

Do
Have a default selection whenever possible. If there’s no logical default, leverage placeholder text.
Sort the list of options in a way that makes the most sense to users.
Provide the ability to search when there is a use case for particular choices.
Don't
Avoid using a MultiSelect if there are less than three options provided in the dropdown.
Beta