React MultiSelect

The React MultiSelect Dropdown with Tags enables the selection of multiple options with filtering, custom values, grouped items, and full accessibility. Ideal for React tag inputs, search filters, and data-rich UIs.

Getting Started with the React MultiSelect

To create a new Vite project, refer to the Vite documentation. Once that Vite project is ready to run with default settings, let's add the React MultiSelect component to the project.

Installing Syncfusion® React packages

To use the React MultiSelect component in this project, the @syncfusion/react-dropdowns package needs to be installed using the following command:

npm install @syncfusion/react-dropdowns

Adding CSS reference

In this article, the Material theme is applied using CSS styles, which are available in installed packages. The necessary Material CSS styles for the MultiSelect component and its dependents were imported into the src/App.css file.

@import '../node_modules/@syncfusion/react-base/styles/material.css';
@import '../node_modules/@syncfusion/react-lists/styles/material.css';
@import '../node_modules/@syncfusion/react-inputs/styles/material.css';
@import '../node_modules/@syncfusion/react-popups/styles/material.css';
@import '../node_modules/@syncfusion/react-buttons/styles/material.css';
@import '../node_modules/@syncfusion/react-dropdowns/styles/material.css'

Adding MultiSelect component

To include the MultiSelect component in your application, import the MultiSelect from the @syncfusion/react-dropdowns package in App.tsx.

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

Add the MultiSelect component in application as shown in below code example.

'use client';
import { MultiSelect } from '@syncfusion/react-dropdowns';
import './app.css';

interface Preference {
  id: number;
  name: string;
}

const travelPreferences: Preference[] = [
  { id: 1, name: 'Direct flights only' },
  { id: 2, name: 'Window seat' },
  { id: 3, name: 'Aisle seat' },
  { id: 4, name: 'Vegetarian meals' },
  { id: 5, name: 'Vegan meals' },
  { id: 6, name: 'Extra legroom' },
  { id: 7, name: 'Red-eye flights' },
  { id: 8, name: 'Early morning flights' },
  { id: 9, name: 'Near city center hotels' },
  { id: 10, name: 'Free cancellation' },
  { id: 11, name: 'Carry-on only' },
  { id: 12, name: 'Avoid overnight layovers' },
];

export default function App() {
  const fields = { text: 'name', value: 'id' };

  return (
    <div className='component-section'>
      <MultiSelect
        placeholder="Select preferences"
        dataSource={travelPreferences}
        fields={fields}
        style={{ width: 320 }}
      />
    </div>
  );
}

Run the project

To run the project, use the following command:

npm run dev

The following example demonstrates a basic MultiSelect with a simple list. Start typing to see suggestions, and select an item from the list.

Primitive data binding

The MultiSelect component can be bound to an array of primitive values, such as strings or numbers. This is useful for scenarios where the data is simple and does not require a complex structure.

Remote data binding

The MultiSelect component can be bound to remote data sources like APIs through the DataManager. The dataSource property establishes the connection to external data, while the query property filters and customizes what data is retrieved from the server. This approach is perfect for applications that need to display server-side data without loading everything at once.

Mode

Controls how selected items are visually displayed in the MultiSelect input field.

• Box: Selected items are always shown as individual removable chips.
• Delimiter: Selected items are displayed as plain text separated by a delimiterChar (e.g. ", ").
• Auto: Shows chips when focused, collapses to delimiter-separated text when focus is lost.

Checkbox

Displays checkboxes next to each option in the React MultiSelect, providing clear, explicit multi‑selection control and improving usability for forms, filters, and data‑entry interfaces.

Select All

The showSelectAll property provides a bulk‑selection action that selects all items in a MultiSelect list to be selected or cleared with a minimal interaction. This functionality is available only when checkbox selection is enabled.

Close on select

The closeOnSelect property controls whether the MultiSelect popup should remain open after selecting an item. When set to false, the dropdown stays open, allowing multiple items to be selected continuously without reopening the list.

Maximum selection length

The maximumSelectionLength restricts how many items can be selected in the MultiSelect. Once the limit is reached, all remaining unselected items become disabled, preventing further selection

Hide selected items

The hideSelectedItem hides selected items removes an item from the dropdown list immediately after it is selected.

Custom value

The MultiSelect component supports custom value functionality that allows custom text values to be entered and committed that are not present in the suggestion list. By pressing Enter, users can add custom values to the multiselect, providing flexibility beyond predefined options.

Add tag on blur

The addTagOnBlur adds the typed input as a new tag automatically when the field loses focus, enabled through customValue for values outside the predefined list.

Resizable popup

The MultiSelect component supports a resizable dropdown popup that can be resized for better visibility of long lists and descriptions. By dragging the bottom-right corner of the popup, users can expand or adjust the dropdown to fit their needs.

Grouping

Grouping enables you to organize suggestions into logical categories using the groupBy field mapping. This improves navigation and discoverability in large datasets as text is typed into the input their queries.

Filtering

The MultiSelect offers built-in filtering. Set filterable to true so users can narrow choices by typing. Tuning debounceDelay helps balance responsiveness and performance.

Diacritics filtering

The MultiSelect component supports diacritics filtering which will ignore the diacritics and makes it easier to filter the results in international characters lists when the ignoreAccent is enabled.

Grouping with filtering

The MultiSelect component supports grouping along with filtering, allowing users to easily navigate and select items from categorized lists. When filtering is enabled, the component dynamically narrows down the grouped items based on the user's input, enhancing usability especially in large datasets.

Filtering with remote data

The MultiSelect component supports filtering with remote data sources, enabling efficient handling of large datasets. As text is entered into the input field, the component fetches matching results from a remote server, ensuring performance and responsiveness even with extensive data collections.

Virtualization

Virtualization keeps the MultiSelect fast with very large datasets by creating DOM nodes only for visible items; demos show common patterns for local and remote data and how to tune rendering and fetch behavior.

• itemSize: Fixed row height in pixels — set to the actual rendered height so scroll math is accurate.
• pageSize: Items per fetch/render batch — larger values mean fewer requests but higher memory/initial cost.
• overscanCount: Extra items rendered above/below the viewport to prevent gaps during fast scrolling and improve smoothness.
• showSkeleton: When true, render lightweight placeholder rows while remote data is loading to improve perceived performance.
• scrollMode: FetchViewPort requests pages incrementally as the list is scrolled (server must handle paging/filtering/grouping); FetchAll expects the full dataset and renders it up front.

This demo contains plain, grouped and filterable examples.

Remote data

Virtualize the MultiSelect when loading data from a server to improve performance.

• Built-in DataManager: Configure DataManager with the remote URL and adapter; it will handle requests and paging for the MultiSelect.
• Custom fetch: Retrieve arrays using fetch() (or another client fetch), assign the returned array to the MultiSelect's dataSource.

Lazy loading data

Lazy loading fetches data as the list scroll position changes, minimizing initial load time and memory usage; use either built-in DataManager virtualization or a custom fetch depending on your backend and control needs.

• Built-in DataManager: set virtualization: { scrollMode: ScrollMode.FetchViewPort } so DataManager requests pages as the viewport changes; filtering can be forwarded, but grouping/sorting must be done server-side.
• Custom fetch: load the first page into dataSource, use onScroll (with a threshold) to detect near-bottom, fetch the next page, and concat results into dataSource. Implement grouping and sorting on the server.

Cascading dropdown

The MultiSelect component supports cascading multiselect functionality where the selections made in one dropdown determine the available options in the subsequent dropdowns.

In this example:

• First, select one or more product categories in the first multiselect.
• Then, select one or more subcategories in the second multiselect (options depend on the selected categories).
• Finally, select one or more brands in the third multiselect (options depend on the selected subcategories).

Custom rendering

The MultiSelect component supports various options to customize the appearance and structure of the dropdown elements.

Value template

The valueTemplate defines how the selected items are visually displayed in the input area, allowing customization of text, layout, or formatting of each selected value.

Chip template

The chipTemplate defines how each selected item's chip is individually customized, allowing full control over the chip’s appearance and formatting.

Item template

The MultiSelect component allows you to customize the appearance of each item in the MultiSelect using the itemTemplate property. This is useful for displaying additional information or styling items in a specific way. The itemTemplate function receives each item's data and returns HTML elements (such as avatar initials, name, and status) with the required class names defined in the style file, enabling simple and flexible rendering of each list item.

Group template

The MultiSelect component allows you to customize the appearance of group headers using the groupTemplate property. This is useful for displaying additional information or styling group headers in a specific way. The groupTemplate function receives the items' data, reads the status, calculates a summary (such as item count and total budget with currency formatting), and returns an HTML block with class names. These class names are styled in the style file and can be easily customized as per requirements.

Header template

The MultiSelect component allows you to add a custom header at the top of the popup list using the headerTemplate property. This is useful for displaying titles, helper text, or other contextual information above the multiselect list items. The headerTemplate function returns the customized title content, such as "Suggested contacts", which appears as the header of the multiselect.

Footer template

The MultiSelect component allows you to add a custom footer at the bottom of the popup list using the footerTemplate property. This is useful for displaying additional information, links, or actions like "Add new" or "View all" below the multiselect list items. The footerTemplate function returns an "Add products" element, which is rendered below the list and can be customized as needed.

No records template

The MultiSelect component allows you to customize the message displayed using the noRecordsTemplate property when no data is available or when filtering returns no results. This enhances the user experience by providing a more informative or branded message instead of a generic "No records found."

Variants

The MultiSelect component enhances user interaction through its three distinct visual variants: Standard, Outlined and Filled.

Appearance

The MultiSelect component provides various options to customize its appearance, including the ability to disable specific items in the dropdown menu. This feature is useful when certain options should be visible but not selectable in particular contexts.

Disabled

The MultiSelect component can be completely disabled by setting the disabled property to true. When disabled, the component becomes non-interactive and visually indicates its disabled state to the user. The example below demonstrates a fully disabled MultiSelect:

Note: This is different from disabling individual items within the dropdown (which is shown in the "Disabled items" section). The disabled property affects the entire component.

Read only

The MultiSelect component can be set to a read-only state by setting the readOnly property to true. In this state, the component displays its current value but doesn't allow any interaction with the dropdown functionality. The example below demonstrates a MultiSelect in read-only mode:

Note: The read-only state differs from the disabled state. While both prevent changes to the selection, a read-only multiselect maintains its visual appearance and can receive focus, whereas a disabled multiselect appears visually inactive and cannot receive focus.

Float label

The MultiSelect component supports different label display modes through the labelMode property. This property controls how the label or placeholder text appears in relation to the input field.

Available label mode options:

• "Never": The label will never float in the input when the placeholder is available.
• "Always": The floating label will always float above the input.
• "Auto": The floating label will float above the input after focusing or entering a value in the input.

The following sample illustrates how the MultiSelect behaves with different label mode settings, showing how each option affects the appearance and interaction of labels.

Invalid

The MultiSelect component can be styled to indicate an invalid state using the "sf-error" class. This is particularly useful in form validation scenarios where user input is required or incorrect.

Disabled items

The MultiSelect component allows specific items in the list to be disabled in the dropdown lists, preventing users from selecting them. This is useful when certain options should be visible but not selectable in particular contexts.

To disable items, include a boolean property in your data objects (like disabled: true) and map it to the disabled field in the fields configuration object.

Controlled vs uncontrolled

The MultiSelect component supports both controlled and uncontrolled modes. In controlled mode, selected value is managed externally using the value property. Any change in selection must be handled through onChange callback event. while uncontrolled mode, the component manages its own state internally. Setting an initial value using the defaultValue property, and the component handles further updates automatically.

Forms support

The MultiSelect component integrates seamlessly with forms, providing built-in validation capabilities. The component supports form validation through properties like validityStyles, valid, and validationMessage. The example below demonstrates an event registration form with validation for participant name and ticket tier selection:

Accessibility

The MultiSelect follows accessibility guidelines and standards, including ADA, Section 508, WCAG 2.2 standards, and WCAG roles.

The accessibility compliance for the MultiSelect component is outlined below.

- All features of the component meet the requirement.

- Some features of the component do not meet the requirement.

- The component does not meet the requirement.

WAI-ARIA attributes

The MultiSelect follows the WAI-ARIA patterns to meet accessibility requirements. The following ARIA attributes are used:

MultiSelect input

Popup listbox

Keyboard interaction

The following keyboard shortcuts enable navigation and item selection in the MultiSelect.

When focus is on the MultiSelect input (popup closed)

When the popup list is open