You are viewing the legacy documentation of Plasma featuring the components from the@coveord/plasma-react and @coveord/plasma-style packages. Those packages are deprecated and replaced by the @coveord/plasma-mantine package.

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.

View source

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

Name	Type	Default	Description
`id`required	`string`		Unique identifier
`active`	`number`
`addSelect`	`() => IReduxAction<ISelectPayload>`
`children`	`ReactNode`
`classes`	`string[]`		Additional CSS classes to set on the list element
`deselectAllTooltipText`	`string`	`"Deselect All"`	The text displayed when hovering over the deselect all button
`disabled`	`boolean`		Whether the SingleSelect is disabled
`dropClasses`	`string`		Additional CSS classes to set on the dropdown element
`dropOption`	`Partial<IDropPodProps>`		Additional Drop props to set on the Drop component (see IDropPodProps interface)
`emptyPlaceholder`	`string`	`"No selected option"`	The text displayed in the multi select box when no items are selected
`footer`	`ReactNode`		Content that is displayed underneath the list of items inside the dropdown
`hasFocusableChild`	`boolean`		Whether the dropdown has a child that needs to receive the focus upon opening the dropdown, for example: a filter input.
`isLoading`	`boolean`		Whether the items are currenty loading (being fetched). If true, it will render visual loading placeholders in the ListBox
`isOpened`	`boolean`
`items`	`IItemBoxProps[]`		The list of items to display as potential choices
`multiSelectStyle`	`CSSProperties`	`{}`	Additional CSS inline style to add on the multiselect container
`noActive`	`boolean`		If true, no highlight will be rendered on active items. An item is active when using keyboard navigation
`noDisabled`	`boolean`	`false`	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.
`noResultItem`	`IItemBoxProps`	`{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.
`placeholder`	`string`	`"Select an option"`	The text displayed in the button when no item is selected
`readOnly`	`boolean`		Whether the multiselect is in read only mode. When in read only mode, only the selected option are displayed, greyed out.
`removeSelect`	`() => IReduxAction<ISelectPayload>`
`selectClasses`	`string`		Additional CSS classes to set on the outermost element
`selectedValues`	`string[]`
`selectValue`	`(value: string, isMulti: boolean, index?: number) => void`
`setActive`	`(diff: number) => IReduxAction<IListBoxPayload>`
`sortable`	`boolean`	`false`	Whether the selected items can be reordered using drag-and-drop
`toggleClasses`	`string`		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 items–The 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