Form

Multi Select

A multi select allows users to select multiple options from a list. It is typically used when there are a large number of options.
1
import {MultiSelectConnected} from '@coveord/plasma-react';
2
3
const Demo = () => (
4
<MultiSelectConnected
5
id="mutli-select-1"
6
items={[
7
{value: 'one', displayValue: 'Option 1'},
8
{value: 'two', displayValue: 'Option 2'},
9
{value: 'three', displayValue: 'Option 3'},
10
]}
11
/>
12
);
13
export default Demo;

Props

NameTypeDefaultDescription
idrequiredstring
Unique identifier
activenumber
addSelect() => IReduxAction<ISelectPayload>
childrenReactNode
classesstring[]
Additional CSS classes to set on the list element
deselectAllTooltipTextstring"Deselect All"
The text displayed when hovering over the deselect all button
disabledboolean
Whether the SingleSelect is disabled
dropClassesstring
Additional CSS classes to set on the dropdown element
dropOptionPartial<IDropPodProps>
Additional Drop props to set on the Drop component (see IDropPodProps interface)
emptyPlaceholderstring"No selected option"
The text displayed in the multi select box when no items are selected
footerReactNode
Content that is displayed underneath the list of items inside the dropdown
hasFocusableChildboolean
Whether the dropdown has a child that needs to receive the focus upon opening the dropdown, for example: a filter input.
isLoadingboolean
Whether the items are currenty loading (being fetched). If true, it will render visual loading placeholders in the ListBox
isOpenedboolean
itemsIItemBoxProps[]
The list of items to display as potential choices
multiSelectStyleCSSProperties{}
Additional CSS inline style to add on the multiselect container
noActiveboolean
If true, no highlight will be rendered on active items. An item is active when using keyboard navigation
noDisabledbooleanfalse
Setting this to true allows to open the dropdown even if all the items are selected. It is useful if adding custom values is allowed.
noResultItemIItemBoxProps{value: 'No Items'}
The content shown in the list of items when there are no items to display.
onUpdate() => void
A callback function that is executed whenever an update of the items array is required. For example if a filter was applied and the filter is done on the server.
placeholderstring"Select an option"
The text displayed in the button when no item is selected
readOnlyboolean
Whether the multiselect is in read only mode. When in read only mode, only the selected option are displayed, greyed out.
removeSelect() => IReduxAction<ISelectPayload>
selectClassesstring
Additional CSS classes to set on the outermost element
selectedValuesstring[]
selectValue(value: string, isMulti: boolean, index?: number) => void
setActive(diff: number) => IReduxAction<IListBoxPayload>
sortablebooleanfalse
Whether the selected items can be reordered using drag-and-drop
toggleClassesstring
Additional CSS classes to set on the toggle button
toggleDropdown() => IReduxAction<ISelectPayload>
wrapItems(items: ReactNode) => ReactNode
Useful if you need to wrap the list of items with another component. We use this when combining with the InfiniteScroll HOC
  • itemsThe list of items in the form of a React Component

Examples

With a filter and custom values
1
import {MultiSelectWithFilter} from '@coveord/plasma-react';
2
3
const Demo = () => (
4
<MultiSelectWithFilter
5
id="mutli-select-2"
6
customValues
7
items={[
8
{value: 'one', displayValue: 'Option 1'},
9
{value: 'two', displayValue: 'Option 2'},
10
{value: 'three', displayValue: 'Option 3'},
11
]}
12
/>
13
);
14
export default Demo;
With predicates
1
import {IItemBoxProps, MultiSelectWithPredicate} from '@coveord/plasma-react';
2
3
const Demo = () => (
4
<MultiSelectWithPredicate
5
id="multi-select-3"
6
items={[
7
{value: '1', displayValue: 'Option 1'},
8
{value: '2', displayValue: 'Option 2'},
9
{value: '3', displayValue: 'Option 3'},
10
{value: '4', displayValue: 'Option 4'},
11
{value: '5', displayValue: 'Option 5'},
12
]}
13
options={[
14
{id: 'all', option: {content: 'All'}, selected: true},
15
{id: 'even', option: {content: 'Even'}},
16
{id: 'odd', option: {content: 'Odd'}},
17
]}
18
matchPredicate={(predicate: string, item: IItemBoxProps) => {
19
const value = parseInt(item.value, 10);
20
switch (predicate) {
21
case 'even':
22
return value % 2 === 0;
23
case 'odd':
24
return value % 2 === 1;
25
default:
26
return true;
27
}
28
}}
29
/>
30
);
31
export default Demo;

Best Practices

Use a Multi select for when users need to filter and select options from a long list. A Multi select is especially appropriate when the available list of options is very long or when space is limited.

List options in alphanumerical order unless a more suited ordering rationale applies. For example, when listing size (large to small) or security level options (full access to limited access).

When a list contains 20 or more options, include the ability to filter them.

Labeling

Keep titles and labels short, preferably under three words.

Title

The title should indicate the type of information to provide.

Provide a descriptive title without action verbs. For example, write "Grocery list" rather than "Select the desired items".

Labels

Labels identify each option and should be self-explanatory. The width of the input should allow to fully display the label of the selected option.

Use a consistent writing style for all options in the list.

Help Text and Instructions

The placeholder text should indicate the type of information to select. Use an action verb. For example, write "Select an ingredient" rather than "Select an option".

Feedback and Validation

Allow the addition of custom values only when it doesn't increase the risk of failure and when there's a possibility that not all available options are listed.

Examples:

  • When users select countries: do not allow custom values.
  • When users build a grocery list: allow custom values so that users can request new products that may not be on the list yet.

Related Components

If your use case doesn't match the guidelines above, consider using one of the following components instead:

  • Multiline box - When space is not an issue or when legibility of the selected option is critical.
  • Checkbox - When there are seven options or less.
  • Single select - When users can select only one option from the list.
Edit guidelines