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:

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.

isItemDisabled

Use the isItemDisabled property to disable items in the list from being interacted with. An item can be selected, but disabled. If not used with the hook useMultiSelectValues the selectAll and clearAll properties must handle the disabled state.

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 need custom renderers, and a custom getSearchText function. 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:

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 Deprecated! No longer has any effect. 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
isItemDisabled (value:T) => boolean; Determine if an item is disabled and hence interactable in the UI

Search Gunnel

Powered byAlgolia