Skip to main content

Multiselect

A <select> alternative multiple values.

Overview#

The <Multiselect> renders an array of data and manages the selection, filtering and value state.

Like other React Widget components, data can be complex; not limited to strings or numbers.

Custom Rendering#

Keyboard shortcuts#

  • left arrow move focus to previous tag
  • right arrow move focus to next tag
  • delete deselect focused tag
  • backspace deselect next tag
  • alt + up arrow close Multiselect
  • down arrow open Multiselect, and move focus to next item
  • up arrow move focus to previous item
  • home move focus to first item
  • end move focus to last item
  • enter select focused item
  • ctrl + enter create new tag from current searchTerm
  • any key search list for item starting with key

API#

allowCreate#

Enables the list option creation UI. onFilter will only the UI when actively filtering for a list item.

type: truefalse'onFilter'
default:false

autoFocus#

Pass focus to the Multiselect when it mounts.

type: boolean

busy#

Controls the loading/busy spinner visibility. Presentational only! Useful for providing visual feedback while data is being loaded.

type: boolean

busySpinner#

Specify the element used to render the busy indicator

type: node

clearTagIcon#

Specify the element used to render tag clear icons.

type: ReactReactNode
default:times

containerClassName#

Adds a css class to the input container element.

type: string

data#

An array of possible values for the Multiselect.

Tip: When data is an array of objects consider specifying textField and dataKey as well.

type: array
default:[]

dataKey#

A property name that provides the value of the data items. This value is used to uniquely distinigush items from others in the data list.

Generally, dataKey points to an Id field, or other unique identifier. When not provided, the referential identity of each data item is used.

type: string(dataItem?) => string

defaultOpen#

type:
default:false

defaultSearchTerm#

type:
default:''

defaultValue#

type:
default:[]

disabled#

type: booleanArray

dropUp#

Controls the opening direction of the Multiselect popup.

type: boolean

filter#

Enable and customize filtering behavior for the Multiselect. Specify one of the built-in methods ("startsWith" "eq" "contains") or provide a function that returns true or false for each passed in item (analogous to the array.filter builtin)

You can explicitly disable filtering by setting filter to false.

type:
default:'startsWith'

focusFirstItem#

type:
default:false

groupBy#

To display grouped lists, specify a property name, or accesor function, whose value is used to group the data list.

The groupBy value is also used as the text for group headings when groupComponent is not provided.

type: string(dataItem?) => string

handleOpen#

type: function

inputProps#

An object of props that is passed directly to the underlying input component.

type: Object

listComponent#

type:
default:List

listProps#

An object of props that is passed directly to the underlying List component.

type: Object

messages#

Object hash containing display text and/or text for screen readers. Use the messages object to localize widget text or provide custom rendering.

type:

onChange#

A callback fired when the current value changes.

type: {function ( dataItems: ?any[], metadata: { dataItem: any, action: 'insert' | 'remove', originalEvent: SyntheticEvent, lastValue: ?any[], searchTerm: ?string } ): void}

onCreate#

This handler fires when the user chooses to create a new list option. It is up to the widget parent to implement creation logic, a common implementation is shown below, where the new tag is selected and added to the data list.

type: { (searchTerm: string) => void }

onSearch#

A callback fired when the current searchTerm changes.

type: {function ( searchTerm: ?string, metadata: { action: 'clear' | 'input', lastSearchTerm: ?string, originalEvent: SyntheticEvent, } ): void}

onSelect#

This handler fires when an item has been selected from the list. It fires before the onChange handler and fires regardless of whether the value has actually changed.

type: { (dataItem: ?any, metadata: { originalEvent: SyntheticEvent }) => void }

open#

Controls the visibility of the Multiselect popup. Use defaultOpen to set an initial value for uncontrolled widgets.

type: boolean

placeholder#

Text to display in the input when the value is empty.

type: string

popupComponent#

type:
default:BasePopup

popupTransition#

A Transition component from react-transition-group. The provided component will be used instead of the default SlideDownTransition for fully customizable animations. The transition component is also injected with a dropUp prop indicating the direction it should open.

type: elementType

readOnly#

Controls the read-only state of the Multiselect.

type: boolean

renderListGroup#

Customize the rendering of the group headings when groupBy is active.

type: function

renderListItem#

Customize the rendering of each Multiselect list item.

type: function

renderTagValue#

type: RenderTagProp<TDataItem>

searchTerm#

Controls the value of the search text used to filter undefined items. searchTerm is only applicable when filtering is enabled.

Use defaultSearchTerm instead to set an initial value for uncontrolled widgets.

type: string

selectIcon#

Specify the element used to render the select (down arrow) icon.

type: node

showPlaceholderWithValues#

Continue to show the input placeholder even if tags are selected

type: boolean
default:false

showSelectedItemsInList#

Continue to show the selected items in the dropdown list

type: boolean
default:false

tagListComponent#

type: ReactComponentType<MultiselectTagListProps<DataItem>>
default:<MultiselectTagList>

tagOptionComponent#

type: TagComponentProp

textField#

A property name, or accessor function, that provides the text content of the data items. The Multiselect will filter data based on this value as well as use it as the default display value for list items and selected values.

type: string(dataItem?) => string

value#

Controls the current value of the Multiselect.

type: array