Multiselect
A <select>
alternative multiple values.
#
OverviewThe <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
#
APIallowCreate#
Enables the list option creation UI. onFilter
will only the UI when
actively filtering for a list item.
false
autoFocus#
Pass focus to the Multiselect when it mounts.
busy#
Controls the loading/busy spinner visibility. Presentational only! Useful for providing visual feedback while data is being loaded.
busySpinner#
Specify the element used to render the busy indicator
clearTagIcon#
Specify the element used to render tag clear icons.
times
containerClassName#
Adds a css class to the input container element.
data#
An array of possible values for the Multiselect.
Tip: When data
is an array of objects
consider specifying
textField
and dataKey
as well.
[]
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.
defaultOpen#
false
defaultSearchTerm#
''
defaultValue#
[]
disabled#
dropUp#
Controls the opening direction of the Multiselect popup.
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
.
'startsWith'
focusFirstItem#
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.
handleOpen#
inputProps#
An object of props that is passed directly to the underlying input component.
listComponent#
List
listProps#
An object of props that is passed directly to the underlying List
component.
messages#
Object hash containing display text and/or text for screen readers.
Use the messages
object to localize widget text or provide custom rendering.
onChange#
A callback fired when the current value
changes.
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.
onSearch#
A callback fired when the current searchTerm
changes.
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.
open#
Controls the visibility of the Multiselect popup. Use defaultOpen
to set an initial value for uncontrolled widgets.
placeholder#
Text to display in the input when the value is empty.
popupComponent#
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.
readOnly#
Controls the read-only state of the Multiselect.
renderListGroup#
Customize the rendering of the group headings when groupBy
is active.
renderListItem#
Customize the rendering of each Multiselect list item.
renderTagValue#
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.
selectIcon#
Specify the element used to render the select (down arrow) icon.
showPlaceholderWithValues#
Continue to show the input placeholder even if tags are selected
false
showSelectedItemsInList#
Continue to show the selected items in the dropdown list
false
tagListComponent#
<MultiselectTagList>
tagOptionComponent#
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.
value#
Controls the current value of the Multiselect.