syncfusion-react-multiselect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React MultiSelect

实现Syncfusion React MultiSelect

A comprehensive skill for implementing the Syncfusion React MultiSelect Dropdown component — enabling users to select multiple values from a list with support for filtering, grouping, templates, checkboxes, chips, virtual scrolling, and more.

这是一套用于实现Syncfusion React MultiSelect Dropdown组件的完整指南，支持用户从列表中选择多个值，同时支持过滤、分组、模板、复选框、芯片、虚拟滚动等特性。

Component Overview

组件概述

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';
// Also import base dependencies:
// @syncfusion/ej2-base/styles/tailwind3.css
// @syncfusion/ej2-buttons/styles/tailwind3.css
// @syncfusion/ej2-inputs/styles/tailwind3.css

Package:

@syncfusion/ej2-react-dropdowns

Main component:

MultiSelectComponent

Checkbox module:

CheckBoxSelection

(inject via

<Inject services={[CheckBoxSelection]} />

)
Virtual scroll module:

VirtualScroll

(inject via

<Inject services={[VirtualScroll]} />

)

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';
// Also import base dependencies:
// @syncfusion/ej2-base/styles/tailwind3.css
// @syncfusion/ej2-buttons/styles/tailwind3.css
// @syncfusion/ej2-inputs/styles/tailwind3.css

包：

@syncfusion/ej2-react-dropdowns

主组件：

MultiSelectComponent

复选框模块：

CheckBoxSelection

（通过

<Inject services={[CheckBoxSelection]} />

注入）
虚拟滚动模块：

VirtualScroll

（通过

<Inject services={[VirtualScroll]} />

注入）

Quick Start Example

快速入门示例

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = ['Badminton', 'Basketball', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      placeholder="Select sports"
    />
  );
}

With objects and field mapping:

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = [
    { id: 'game1', sports: 'Badminton' },
    { id: 'game2', sports: 'Football' },
    { id: 'game3', sports: 'Tennis' },
  ];
  const fields = { text: 'sports', value: 'id' };

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
    />
  );
}

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = ['Badminton', 'Basketball', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      placeholder="Select sports"
    />
  );
}

对象与字段映射示例：

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = [
    { id: 'game1', sports: 'Badminton' },
    { id: 'game2', sports: 'Football' },
    { id: 'game3', sports: 'Tennis' },
  ];
  const fields = { text: 'sports', value: 'id' };

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
    />
  );
}

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and package setup (Vite / CRA)
CSS imports and theming
Basic MultiSelect implementation (class & functional components)
Binding a simple data source
Popup height/width configuration

📄 阅读： references/getting-started.md

安装与包配置（Vite / CRA）
CSS导入与主题配置
基础MultiSelect实现（类组件与函数组件）
简单数据源绑定
弹窗高度/宽度配置

Data Binding

数据绑定

📄 Read: references/data-binding.md

Array of strings vs array of objects
Field mapping (
```
text
```
,
```
value
```
,
```
groupBy
```
,
```
iconCss
```
,
```
disabled
```
)
Remote data via
```
DataManager
```
(OData, OData V4, Web API)
JSON/JSONP formats
Complex data binding gotchas

📄 阅读： references/data-binding.md

字符串数组 vs 对象数组
字段映射（
```
text
```
、
```
value
```
、
```
groupBy
```
、
```
iconCss
```
、
```
disabled
```
）
通过
```
DataManager
```
对接远程数据（OData、OData V4、Web API）
JSON/JSONP格式支持
复杂数据绑定注意事项

Grouping

分组

📄 Read: references/grouping.md

Grouping items by category with
```
groupBy
```
Inline vs fixed group headers
Group header templates
Ordering and multi-level grouping

📄 阅读： references/grouping.md

通过
```
groupBy
```
按类别对选项分组
行内 vs 固定分组头部
分组头部模板
排序与多级分组

Filtering

过滤

📄 Read: references/filtering.md

Enabling
```
allowFiltering
```
Handling the
```
filtering
```
event
Query API with
```
where()
```
conditions
Filter types: startswith, contains, endswith
Case sensitivity, multiple conditions, performance

📄 阅读： references/filtering.md

开启
```
allowFiltering
```
处理
```
filtering
```
事件
带
```
where()
```
条件的查询API
过滤类型：开头匹配、包含匹配、结尾匹配
大小写敏感、多条件配置、性能优化

Templates

模板

📄 Read: references/templates.md

Item templates for custom list item layouts
Value/chip templates for selected display
Group header templates
Header, footer, no-records, and action-failure templates

📄 阅读： references/templates.md

自定义列表项布局的项模板
选中项展示的取值/芯片模板
分组头部模板
头部、底部、无记录、操作失败模板

Selection Modes and Features

选择模式与特性

📄 Read: references/selection-and-features.md

Checkbox mode (inject
```
CheckBoxSelection
```
)
Chip/tag display and the
```
tagging
```
event
Custom values (
```
allowCustomValue
```
)
Value binding (primitive and object types)
Disabled items via
```
fields.disabled
```
Popup resizing (
```
allowResize
```
)
Virtual scrolling for large datasets (inject
```
VirtualScroll
```
)

📄 阅读： references/selection-and-features.md

复选框模式（注入
```
CheckBoxSelection
```
）
芯片/标签展示与
```
tagging
```
事件
自定义值（
```
allowCustomValue
```
）
值绑定（基础类型与对象类型）
通过
```
fields.disabled
```
禁用指定选项
弹窗大小调整（
```
allowResize
```
）
大数据集的虚拟滚动（注入
```
VirtualScroll
```
）

Accessibility, Styling, and Localization

可访问性、样式与本地化

📄 Read: references/accessibility-styling-localization.md

WAI-ARIA attributes and keyboard shortcuts
WCAG 2.2 / Section 508 / Screen reader support
CSS customization (chips, wrapper, icon, delimiter)
RTL support
Localization with
```
L10n
```

📄 阅读： references/accessibility-styling-localization.md

WAI-ARIA属性与键盘快捷键
WCAG 2.2 / Section 508 / 屏幕阅读器支持
CSS自定义（芯片、容器、图标、分隔符）
RTL支持
通过
```
L10n
```
实现本地化

API Reference

API参考

📄 Read: references/api.md

Complete list of all properties with types, descriptions, and defaults
All public methods with parameter details and return types
All events with their argument types and trigger conditions

📄 阅读： references/api.md

所有属性的完整列表，包含类型、说明和默认值
所有公共方法的参数详情与返回类型
所有事件的参数类型与触发条件

Key Props Reference

核心属性参考

Prop	Type	When to Use
`dataSource`	`string[] \| object[] \| DataManager`	Always required — data to display
`fields`	`FieldSettingsModel`	When using object data; map `text` , `value` , `groupBy` , `disabled`
`mode`	`'Default' \| 'Box' \| 'CheckBox' \| 'Delimiter'`	Change selection display: chips ( `Box` ), checkboxes, or comma-delimited
`value`	`string[] \| number[] \| object[]`	Pre-select items on load
`allowFiltering`	`boolean`	Enable search-as-you-type filtering
`allowCustomValue`	`boolean`	Let users type values not in the list
`allowObjectBinding`	`boolean`	Return full objects as selected values instead of primitives
`enableVirtualization`	`boolean`	Use for 500+ items to improve performance
`allowResize`	`boolean`	Let users resize the popup
`popupHeight`	`string`	Limit popup list height (default: `300px` )
`popupWidth`	`string`	Set popup width (default: matches input)
`placeholder`	`string`	Input placeholder text

属性	类型	使用场景
`dataSource`	`string[] \	object[] \
`fields`	`FieldSettingsModel`	使用对象类型数据时使用，用于映射 `text` 、 `value` 、 `groupBy` 、 `disabled` 字段
`mode`	`'Default' \	'Box' \
`value`	`string[] \	number[] \
`allowFiltering`	`boolean`	开启输入时即时搜索过滤功能
`allowCustomValue`	`boolean`	允许用户输入列表中不存在的自定义值
`allowObjectBinding`	`boolean`	选中值返回完整对象而非基础类型值
`enableVirtualization`	`boolean`	选项数量超过500时使用，提升渲染性能
`allowResize`	`boolean`	允许用户调整弹窗大小
`popupHeight`	`string`	限制弹窗列表高度（默认： `300px` ）
`popupWidth`	`string`	设置弹窗宽度（默认：与输入框宽度一致）
`placeholder`	`string`	输入框占位提示文本

Common Use Cases

常见使用场景

Multi-tag input (chip display): → Use

mode="Box"

(default). Each selection becomes a chip.

Checkbox multi-selection: → Use

mode="CheckBox"

and inject

CheckBoxSelection

module.

Search/filter a long list: → Set

allowFiltering={true}

and handle the

filtering

event for remote data.

Pre-select values: → Pass

value

prop as an array of value-field values:

value={['id1', 'id2']}

Group by category: → Add

groupBy

to the

fields

prop:

fields={{ text: 'name', value: 'id', groupBy: 'category' }}

Large datasets (1000+ items): → Set

enableVirtualization={true}

and inject

VirtualScroll

module.

Disable specific options: → Add a boolean

disabled

column to your data and map it:

fields={{ ..., disabled: 'isDisabled' }}

Custom entry not in list: → Set

allowCustomValue={true}

; handle

customValueSelection

event for custom actions.

多标签输入（芯片展示）： → 使用

mode="Box"

（默认），每个选中项会展示为一个芯片。

复选框多选： → 使用

mode="CheckBox"

并注入

CheckBoxSelection

模块。

搜索/过滤长列表： → 设置

allowFiltering={true}

，远程数据需额外处理

filtering

事件。

预选中值： → 传入

value

属性，值为取值字段的数组：

value={['id1', 'id2']}

。

按类别分组： → 在

fields

属性中添加

groupBy

：

fields={{ text: 'name', value: 'id', groupBy: 'category' }}

。

大数据集（1000+项）： → 设置

enableVirtualization={true}

并注入

VirtualScroll

模块。

禁用特定选项： → 在数据源中添加布尔类型的禁用字段并做映射：

fields={{ ..., disabled: 'isDisabled' }}

。

允许输入列表中不存在的自定义内容： → 设置

allowCustomValue={true}

；处理

customValueSelection

事件执行自定义操作。

Decision Guide

决策指南

User wants multiple selections?
  ├── Visual chips with filter → mode="Box" (default) + allowFiltering
  ├── Checkbox-style list      → mode="CheckBox" + Inject CheckBoxSelection
  └── Comma-separated display  → mode="Delimiter"

Data source type?
  ├── Simple strings/numbers   → Pass array directly to dataSource
  ├── Objects                  → Pass array + fields={{ text, value }}
  └── Remote API               → Use DataManager + allowFiltering + filtering event

List is very long?
  └── Yes (500+) → enableVirtualization={true} + Inject VirtualScroll

Need custom item layout?
  └── Use itemTemplate, valueTemplate, groupTemplate props

Need localization?
  └── Read references/accessibility-styling-localization.md

用户需要多选功能？
  ├── 带过滤的可视化芯片 → mode="Box" (默认) + allowFiltering
  ├── 复选框样式列表      → mode="CheckBox" + 注入CheckBoxSelection
  └── 逗号分隔展示  → mode="Delimiter"

数据源类型？
  ├── 简单字符串/数字   → 直接将数组传给dataSource
  ├── 对象                  → 传入数组 + fields={{ text, value }}
  └── 远程API               → 使用DataManager + allowFiltering + filtering事件

列表非常长？
  └── 是（500+） → enableVirtualization={true} + 注入VirtualScroll

需要自定义项布局？
  └── 使用itemTemplate, valueTemplate, groupTemplate props

需要本地化？
  └── 阅读references/accessibility-styling-localization.md