Skip to main content

MultipleSelect

MultipleSelect in Storybook
Note: There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.

Examples​

Check out the Usage section for details about how and when to use MultipleSelect and the specific tabs for details on the features provided by each component.

Note: Most of the features and properties of the four provided Dropdown components do not have usage differences. Some examples from other components might be relevant for MultipleSelect too.

With an initial value​

Example of how to set a basic MultipleSelect component with an initial value assigned.

<MultipleSelect
  label="Your favorite characters"
  initialValue={[{ id: '1', label: 'Anakin' }]}>
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
</MultipleSelect>

No initial value​

Simple MultipleSelect component without an initial value.

<MultipleSelect label="Your favorite characters">
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
</MultipleSelect>

Disabled dropdown or options​

You can disable completely any of the dropdown components by setting the disabled property to true. You can also disable only the specific options using the disabled property of the SelectOption and ComboboxOption components. In case that the whole component is disabled, the disabled property of the options does not have any effect.

Disabled dropdown​

Example of a disabled dropdown component using the MultipleSelect component.

<MultipleSelect
  label="Your favorite character"
  initialValue={[{ id: '1', label: 'Anakin' }]}
  disabled={true}>
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
</MultipleSelect>

Disabled options​

Example of the MultipleSelectcomponent with some dropdown options disabled:

<MultipleSelect
  label="Your favorite character"
  initialValue={[{ id: '2', label: 'Luke' }]}>
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
    disabled={true}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
  <SelectOption
    value={{
      id: '3',
      label: 'Yoda',
    }}
  />
  <SelectOption
    value={{
      id: '4',
      label: 'Solo',
    }}
    disabled={true}
  />
</MultipleSelect>

DisplayOnly dropdown​

By setting the displayOnly property to true, the component value will be displayed as plain text.

An example is shown below:

<MultipleSelect
  label="Your favorite characters (Multiple Select component)"
  initialValue={[{ id: '1', label: 'Anakin' }]}
  displayOnly={true}>
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
</MultipleSelect>

Controlled component​

This is a common behavior for all of the dropdown components: when the value property is set, the user cannot directly modify the component, it will be managed entirely by the developer implementation.

This example is applicable to all dropdown components:

export function MultiSelectControlled() {
  const [updatedValue, setNewValue] = useState([]);

  const onChange = (e, newValue) => {
    setNewValue(newValue);
  };

  const options = [
    <SelectOption
      value={{
        id: '1',
        label: 'Option 1',
      }}
    />,
    <SelectOption
      value={{
        id: '2',
        label: 'Option 2',
      }}
    />,
    <SelectOption
      value={{
        id: '3',
        label: 'Option 3',
      }}
    />,
    <SelectOption
      value={{
        id: '4',
        label: 'Option 4',
      }}
    />,
    <SelectOption
      value={{
        id: '5',
        label: 'Option 5',
      }}
    />,
  ];

  return (
    <div>
      <MultipleSelect
        label="Choose values"
        secondaryLabel="This value will be passed to the list of options below"
        onChange={onChange}>
        {options}
      </MultipleSelect>
      <br />
      <MultipleSelect
        label="Changes with the above"
        value={updatedValue}>
        {options}
      </MultipleSelect>
    </div>
  );
}

Set focus on the dropdown​

Using the ref property and the imperative handlers provided ('focus', 'blur' and 'scrollIntoView') it is possible to perform different native actions. An example is to set the focus on the component.

See the example below with Select component:

export function MultiSelectRef() {
  const selectRef = useRef(null);

  const setFocus = (e) => {
    selectRef?.current?.focus();
  };

  return (
    <div>
      <Button
        label="Set focus on Select"
        onClick={setFocus}></Button>
      <Select
        label="Get the focus from the button"
        ref={selectRef}>
        <SelectOption
          value={{
            id: '1',
            label: 'Option 1',
          }}
        />
        <SelectOption
          value={{
            id: '2',
            label: 'Option 2',
          }}
        />
      </Select>
    </div>
  );
}

Component validation​

The dropdown components do not handle the validation process, but you can handle the error status and the messages to be displayed using the stateMessages property.

The state messages logic works for all dropdown components, below is an example of MultipleSelect:

export function MultiSelectValidation() {
  const [validationMessages, setValidationMessages] = useState({});

  const onChange = useCallback((e, newValue) => {
    setValidationMessages({});

    if (newValue && newValue.length < 2) {
      setValidationMessages({
        error: ['Select at least 2 options'],
      });
    }
  }, []);

  return (
    <MultipleSelect
      label="Select at least 2 options"
      stateMessages={validationMessages}
      onChange={onChange}>
      <SelectOption
        value={{
          id: '1',
          label: 'Option 1',
        }}
      />
      <SelectOption
        value={{
          id: '2',
          label: 'Option 2',
        }}
      />
      <SelectOption
        value={{
          id: '3',
          label: 'Option 3',
        }}
      />
      <SelectOption
        value={{
          id: '4',
          label: 'Option 4',
        }}
      />
      <SelectOption
        value={{
          id: '5',
          label: 'Option 5',
        }}
      />
    </MultipleSelect>
  );
}