MultiSelect Component

The MultiSelect component provides an input with an integrated dropdown popup for selecting multiple options from a list. It supports controlled and uncontrolled usage, local or remote data sources, filtering, custom value creation, tag/delimiter display modes, checkbox selection, select all functionality, and virtualization for large datasets.

Usage

To import and use the MultiSelect component in your application, use the following code snippet:

import { MultiSelect } from "@syncfusion/react-dropdowns";

export default function App() {
const data = [
  { text: "Apple", value: "apple" },
  { text: "Banana", value: "banana" },
  { text: "Cherry", value: "cherry" }
];
return (
  <MultiSelect
    id="fruits"
    dataSource={data}
    fields={{ text: "text", value: "value" }}
    placeholder="Select fruits" />
);
}

import { MultiSelect } from "@syncfusion/react-dropdowns";

export default function App() {
const data = [
  { text: "Apple", value: "apple" },
  { text: "Banana", value: "banana" },
  { text: "Cherry", value: "cherry" }
];
return (
  <MultiSelect
    id="fruits"
    dataSource={data}
    fields={{ text: "text", value: "value" }}
    placeholder="Select fruits" />
);
}

Demos

Explore the demos of the React MultiSelect component. Refer to this page.

Props

The following table outlines the props for the MultiSelect component:

Name	Type	Default	Description
addTagOnBlur	boolean	false	Specifies whether typed text converts to tags when focus exits the input area.
allowObjectBinding	boolean	false	Specifies whether to allow binding of complex objects as values instead of primitive values. When enabled, the entire object can be accessed in events.
checkbox	boolean	false	Specifies whether to enable checkbox for selecting multiple values.
chipTemplate	(Item: T) => node	-	Specifies a custom template for selected chips.
clearButton	boolean \| node	false	Specifies whether to show a clear button in the dropdown component. When enabled, a clear icon appears when a value is selected, allowing users to clear the selection.
closeOnSelect	boolean	false	Specifies whether the dropdown closes after item selection.
customValue	boolean	false	Specifies whether users can commit custom text values (not in the suggestion list) by pressing Enter. When enabled, free-form input is accepted as a valid selection.
dataSource	DataManager \| T[]	[ ]	Specifies the data source for populating the dropdown items. Accepts various data formats including array of objects, primitive arrays, or DataManager.
debounceDelay	number	0	Specifies the debounce delay (in milliseconds) for filtering input.
defaultOpen	boolean	false	Specifies whether the popup is defaultOpen (uncontrolled).
defaultValue	T[]	-	Specifies the initial selected values for uncontrolled mode.
delimiterChar	string	','	Specifies the character that separates tags in delimiter mode.
dropdownIcon	node	-	Specifies a custom SVG icon to be rendered in the dropdown component input element.
fields	FieldSettingsModel	{ text: 'text', value: 'value', disabled: 'disabled', groupBy: 'groupBy' }	Specifies the mapping fields for text and value properties in the data source objects. Helps in binding complex data structures to the dropdown.
filterType	FilterType	'StartsWith'	Specifies the type of filtering to be applied.
filterable	boolean	false	Specifies whether filtering is enabled in the dropdown component.
footerTemplate	node	-	Specifies a custom template for rendering the footer section of the dropdown popup, enabling additional content below the item list.
groupTemplate	Function \| node	-	Specifies a custom template for rendering group header sections when items are categorized into groups in the dropdown component.
headerTemplate	node	-	Specifies a custom template for rendering the header section of the dropdown popup, enabling additional content above the item list.
hideSelectedItem	boolean	false	Specifies whether to hide selected items from the suggestion list.
ignoreAccent	boolean	false	Specifies whether to ignore diacritics while filtering or selecting items.
ignoreCase	boolean	true	Specifies whether the dropdown component should ignore case while filtering or selecting items.
inputProps	React.InputHTMLAttributes<HTMLInputElement>	-	Specifies additional HTML attributes to apply to the underlying input element. Values provided here can override default aria-* attributes set by the component.
itemTemplate	Function \| node	-	Specifies a custom template for rendering each item in the dropdown component, allowing for customized appearance of list items.
labelMode	LabelMode	'Never'	Specifies the behavior of the floating label associated with the dropdown component input. Determines when and how the label appears.
loading	boolean	false	Specifies whether the component is in loading state. When true, a spinner icon replaces the default caret icon.
maximumSelectionLength	number	0	Specifies the maximum number of items that can be selected in multi-select mode (multiSelectable only). When set to 0 or not specified, there is no limit on selections. This property has no effect in single-select mode.
mode	DisplayMode	DisplayMode.Auto	Specifies the display mode for selected items (Box/Delimiter/Default).
noRecordsTemplate	node	'No Records Found'	Specifies a custom template for the message displayed when no items match the search criteria or when the data source is empty.
onErrorTemplate	node	-	Specifies a custom template to render when an error occurs in the dropdown component.
open	boolean	false	Specifies whether the dropdown popup is open or closed.
openOnClick	boolean	true	Specifies whether to open dropdown on input click.
placeholder	string	-	Specifies the placeholder text that appears in the dropdown component when no item is selected.
popupSettings	PopupSettings	{ width: '100%', height: '300px', zIndex: 1000 }	Specifies popup-specific settings such as width, height, position, offsets, collision, z-index, and auto-reposition behavior.
query	Query	-	Specifies the query to retrieve data from the data source. This is useful when working with DataManager for complex data operations.
required	boolean	-	Specifies whether the component is a required field in a form. When set to true, the component will be marked as required.
resizable	boolean	false	Specifies the value to enable popup resizing functionality.
selectAllText	node	'Select All'	Specifies the text displayed for the bulk selection option in the dropdown header.
showSelectAll	boolean	false	Specifies whether to display bulk selection controls in the dropdown header. When enabled, shows options to select/deselect all items at once.
size	Size	Size.Medium	Specifies the size style of the dropdown component. Options include 'Small', 'Medium' and 'Large'.
skipDisabledItems	boolean	true	Specifies whether disabled items in the dropdown component should be skipped during keyboard navigation. When set to true, keyboard navigation will bypass disabled items, moving to the next enabled item in the list.
sortOrder	SortOrder	SortOrder.None	Specifies the sort order for the dropdown component items.
unSelectAllText	node	'Unselect All'	Specifies the text displayed for clearing all selections in the dropdown header.
valid	boolean	-	Specifies whether to override the validity state of the component. If valid is set, the required property will be ignored.
validationMessage	string	-	Specifies the form error message of the component.
validityStyles	boolean	true	Specifies whether to apply visual representation of the invalid state of the component. If set to false, no visual representation of the invalid state of the component will be applied.
value	T[]	-	Specifies the array of selected values in controlled mode.
valueTemplate	(SelectedItems: T[]) => node	-	Specifies a custom template for rendering the selected value in the input element, allowing for customized appearance of the selection.
variant	Variant	Variant.Standard	Specifies the variant style of the dropdown component. Options include 'Outlined', 'Filled', and 'Standard'.
virtualization	DropdownVirtualProps	-	Provides configuration options for enabling and managing virtualization in the dropdown component. Virtualization enhances performance by only rendering items that are currently visible in the viewport.

Events

The following table outlines the events for the MultiSelect component:

Name	Type	Description
onChange	(args: MultiSelectChangeEvent) => void	Specifies an event that triggers when the selected value of the dropdown component changes, providing details about the new and previous values.
onChipClick	(args: ChipClickEvent) => void	Specifies the event fired when a chip (tag) is selected.
onChipDelete	(item: T) => void	Specifies the event fired when each chip item is removed from the input.
onClose	(event: PopupEvent) => void	Specifies an event that triggers when the dropdown popup closes, allowing for custom actions to be performed at that moment.
onCustomValueSelect	(value: string) => void	Specifies the callback invoked when a custom value (not in the suggestion list) is committed via Enter key. Receives the custom string value as a parameter.
onDataLoad	(event: DataLoadEvent) => void	Specifies an event that triggers after data is fetched successfully.
onDataRequest	(event: DataRequestEvent) => void	Specifies an event that triggers before data is fetched.
onError	(event: Error) => void	Specifies an event that triggers when data fetching fails
onFilter	(event: FilterEvent) => void	Specifies an event that triggers on typing a character in the filter bar when the filtering is enabled.
onOpen	(event: PopupEvent) => void	Specifies an event that triggers when the dropdown popup opens, allowing for custom actions to be performed at that moment.
onResize	(event: ResizeEvent) => void	Specifies the event fired when resizing occurs (applicable when resizable is enabled).
onScroll	(event: ScrollEvent) => void	Specifies an event that triggers when the virtual scrolled.
onSelectAll	(event: SelectAllEvent) => void	Specifies the event fired when all items are selected or deselected using `SelectAll` option.

MultiSelect Component

Usage

Demos

Props

Events

Enhance your React apps with Syncfusion components today