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.

selectAllboolean

If set, a Select All option will be added to the top of the list.

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.