Multi select
The MultiSelect component can be used to select multiple items from a list. It is designed to be used with a list of items, and will allow the user to search for items, select all items, and clear all items.
Example
Usage
Installation
The MultiSelect component is in it’s own package. Install it with npm or yarn.
It is strongly recommended to use the useMultiSelectValues hook to manage the state. See the section below for details.
Options
The following options can be used to control the behavior of the multiselect:
hasSearch- Enable the search box. Defaults totrue.hasSelectAll- Enable the selectAll button. Defaults totrue.itemLimit- Number of selected items to show before overflowing. Defaults to 3.itemMaxLength- Maximum length of a selected item, when using the default label renderer. Longer than this will be truncated. Defaults to 20.- ‘busy’ - Set to true to show a loading spinner.
- ‘disabled’ - Set to true to disable the control.
Customising
Items in the multiselect can be customized to render whatever you like. By default, MultiSelect will assume that items are strings, but this can also be overridden using a type parameter.
renderItem
Override the renderItem property to customize the rendering of the items in the list.
renderLabel
Override the renderLabel property to customize the rendering of the selected items.
By default these are truncated to the length of itemMaxLength.
renderDelimiter
Override the renderDelimiter property to customize the delimiter used when displaying selected items in a row.
By default, a comma is used.
Overriding the value type
By default the multi-select component expects values to be an array of strings, but this can be overriden with a type parameter.
For best effect you will probably need custom renderers too. In this example the list item is an object with {id:string, title:string} properties.
useMultiSelectValues
It is strongly recommended to use the useMultiSelectValues hook to manage the state
of the multi-select component. This hook will handle the logic for selecting, deselecting, and filtering items.
Give it the list of available items and list of initial selected items and it will return an object with the following properties:
displayValues: T[]selectedValues :Set<T>allPossibleValues: T[]missingValues Set<T>selectItem(value:T, isChecked:boolean)selectAll()clearAll()filterDisplayValues(searchTerm: string)
These can be passed to the MultiSelect component as props.
All of the examples above are using useMultiSelectValues.
All properties
| Name | Type | Required | Description |
|---|---|---|---|
| displayValues | T[] | true | List of visible items. This should be affected by searching. |
| selectedValues | Set<T> | true | List of currently selected items. |
| allPossibleValues | T[] | true | List of all possible items. |
| missingValues | Set<T> | true | List of items that are in use but not in the current item list. |
| loading | boolean | Set to true to show a loading spinner. | |
| disabled | boolean | Set to true to disable the control. | |
| emptySearchMessage | string | Message to show when there are no search results. | |
| noValuesMessage | string | Message to show when there are no items in the input. | |
| itemLimit | number | Number of selected items to show before overflowing. Defaults to 3. | |
| itemMaxLength | number | Maximum length of a selected item. Longer than this will be truncated. Defaults to 20. | |
| hasSearch | boolean | Enable the search box. Defaults to true | |
| hasSelectAll | boolean | Enable the selectAll button. Defaults to true | |
| renderDelimiter | () => ReactNode | Renders the delimiter used when displaying selected items in a row. Defaults to , | |
| renderItem | (value:T) => ReactNode | Renders the delimiter used when displaying selected items in a row. Defaults to , | |
| renderLabel | (value:T) => ReactNode | Renders the delimiter used when displaying selected items in a row. Defaults to , | |
| onItemChange | (value: T, isChecked: boolean) => void; | true | Called when an item is selected or de-selected. |
| onSelectAll | () => void; | Called when ‘select all’ happens | |
| onClearAll | () => void; | Called when ‘clear all’ happens | |
| onSearch | (searchTerm:string) => void; | Called when text is entered in the search box |
