Back to Details

syncfusion-react-combobox

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion React ComboBox

实现Syncfusion React ComboBox

Component Overview

组件概述

The ComboBox is a specialized dropdown input that bridges typed input fields with selection lists. Key characteristics:
  • Hybrid input: User can type to filter OR select from dropdown
  • Smart filtering: Default filter searches by text, customizable for complex scenarios
  • Flexible data: Supports strings, JSON objects, OData, Web APIs, DataManager
  • Rich UI: Templates for items, headers, footers, selected values, no-results states
  • Performance: Virtual scrolling efficiently handles thousands of items
  • Global ready: Built-in localization, RTL support, ARIA attributes
  • Accessible: Full keyboard navigation, screen reader support
Installation: 
npm install @syncfusion/ej2-react-dropdowns
ComboBox是一种专用下拉输入组件，衔接了手动输入框和选择列表的能力，核心特性如下：
  • 混合输入： 用户可输入内容过滤选项，也可直接从下拉列表中选择
  • 智能过滤： 默认过滤器按文本搜索，可自定义适配复杂业务场景
  • 灵活数据源： 支持字符串、JSON对象、OData、Web API、DataManager
  • 丰富UI能力： 支持自定义选项、头部、底部、选中值、无结果状态的模板
  • 高性能： 虚拟滚动能力可高效处理数千条选项
  • 全球化适配： 内置本地化、RTL支持、ARIA属性
  • 无障碍访问： 完整的键盘导航、屏幕阅读器支持
安装命令： 
npm install @syncfusion/ej2-react-dropdowns

Documentation Navigation Guide

文档导航指南

Choose your starting point based on your task:
根据你的任务选择对应的入门文档：

Getting Started

快速入门

📄 Read: references/getting-started.md
When to read:
  • Setting up ComboBox in a new project
  • First-time component implementation
  • Understanding basic usage (class vs functional components)
  • Adding CSS imports and themes
  • Enabling custom values
📄 阅读： references/getting-started.md
适用场景：
  • 在新项目中集成ComboBox
  • 首次实现该组件
  • 了解基础用法（类组件 vs 函数组件）
  • 引入CSS和主题配置
  • 开启自定义值输入能力

Data Binding & Sources

数据绑定与数据源

📄 Read: references/data-binding.md
When to read:
  • Binding local data (string arrays, JSON objects)
  • Connecting to remote APIs (OData, Web API, DataManager)
  • Mapping object fields (text, value, groupBy, iconCss)
  • Handling complex data transformations
  • Understanding data source configuration
📄 阅读： references/data-binding.md
适用场景：
  • 绑定本地数据（字符串数组、JSON对象）
  • 对接远程API（OData、Web API、DataManager）
  • 映射对象字段（文本、值、分组字段、图标CSS）
  • 处理复杂数据转换
  • 了解数据源配置规则

Filtering & Search Behavior

过滤与搜索行为

📄 Read: references/filtering-and-search.md
When to read:
  • Implementing text filtering
  • Creating custom filter functions
  • Configuring search behavior (case sensitivity, partial matching)
  • Performance optimization for large datasets
  • Handling no-results scenarios
📄 阅读： references/filtering-and-search.md
适用场景：
  • 实现文本过滤功能
  • 开发自定义过滤函数
  • 配置搜索行为（大小写敏感、部分匹配）
  • 大数据集下的性能优化
  • 处理无搜索结果的场景

Grouping & Sorting

分组与排序

📄 Read: references/grouping-and-sorting.md
When to read:
  • Organizing items into logical groups
  • Customizing group header appearance
  • Applying sort orders (ascending/descending)
  • Combining grouping with filtering
  • Multi-level grouping scenarios
📄 阅读： references/grouping-and-sorting.md
适用场景：
  • 将选项按逻辑分组展示
  • 自定义分组头部样式
  • 配置排序规则（升序/降序）
  • 结合分组与过滤能力
  • 多级分组场景

Templates & Customization

模板与自定义

📄 Read: references/templates-and-customization.md
When to read:
  • Creating custom item templates
  • Displaying rich content (images, icons, descriptions)
  • Header/footer templates (e.g., action buttons, summaries)
  • Selected value template formatting
  • CSS class-based styling and theme customization
📄 阅读： references/templates-and-customization.md
适用场景：
  • 开发自定义选项模板
  • 展示富内容（图片、图标、描述）
  • 头部/底部模板（比如操作按钮、汇总信息）
  • 选中值的模板格式化
  • 基于CSS类的样式和主题自定义

Advanced Features

高级功能

📄 Read: references/advanced-features.md
When to read:
  • Virtual scrolling for large datasets (10,000+ items)
  • Internationalization (i18n) and language switching
  • RTL (right-to-left) support for Arabic/Hebrew
  • Accessibility compliance (WCAG 2.1, ARIA attributes)
  • Disabled states and multi-select workflows
  • Keyboard shortcuts and focus management
📄 阅读： references/advanced-features.md
适用场景：
  • 大数据集（10000+条选项）的虚拟滚动
  • 国际化（i18n）和语言切换
  • 阿拉伯语/希伯来语的RTL（从右到左）支持
  • 无障碍合规（WCAG 2.1、ARIA属性）
  • 禁用状态和多选工作流
  • 键盘快捷键和焦点管理

Styling & Theming

样式与主题

📄 Read: references/styling-and-theming.md
When to read:
  • Applying built-in Syncfusion themes (Material, Bootstrap, Tailwind)
  • CSS variable customization for brand colors
  • Theme Studio integration for design customization
  • Responsive design patterns
  • Dark mode / light mode support
📄 阅读： references/styling-and-theming.md
适用场景：
  • 应用Syncfusion内置主题（Material、Bootstrap、Tailwind）
  • 通过CSS变量自定义品牌色
  • 对接Theme Studio实现设计定制
  • 响应式设计适配
  • 深色/浅色模式支持

Popup Resizing

下拉框缩放

📄 Read: references/popup-resizing.md
When to read:
  • Allowing users to dynamically resize the dropdown
  • Saving resize preferences across sessions
  • Handling long content with custom templates
  • Mobile-friendly dropdown sizing
📄 阅读： references/popup-resizing.md
适用场景：
  • 允许用户动态调整下拉框尺寸
  • 跨会话保存缩放偏好
  • 处理自定义模板的长内容
  • 移动端友好的下拉框尺寸适配

How-To Guide

实操指南

📄 Read: references/how-to-guide.md
When to read:
  • Implementing autofill (auto-complete while typing)
  • Creating cascading/dependent dropdowns (Country → State → City)
  • Displaying icons in list items
  • Common practical implementation scenarios
📄 阅读： references/how-to-guide.md
适用场景：
  • 实现自动填充（输入时自动补全）
  • 开发级联/依赖下拉框（国家→省份→城市）
  • 在列表选项中展示图标
  • 常见的实际落地场景

Troubleshooting

故障排查

📄 Read: references/troubleshooting.md
When to read:
  • Performance issues (slow rendering, lag)
  • Data binding problems
  • Migration from EJ1 ComboBox
  • Common edge cases and workarounds
  • Debugging tips and community resources
📄 阅读： references/troubleshooting.md
适用场景：
  • 性能问题（渲染慢、卡顿）
  • 数据绑定异常
  • 从EJ1 ComboBox迁移
  • 常见边缘场景和解决方案
  • 调试技巧和社区资源

API Reference

API参考

📄 Read: references/api.md
When to read:
  • Looking up a specific property, method, or event name and its type
  • Understanding default values for any configuration option
  • Checking event argument shapes (
    ChangeEventArgs
    , 
    FilteringEventArgs
    , etc.)
  • Reviewing all available methods for programmatic control
  • Exploring interface models (
    FieldSettingsModel
    , 
    PopupEventArgs
    , etc.)
📄 阅读： references/api.md
适用场景：
  • 查找特定属性、方法、事件名称和类型
  • 了解任意配置项的默认值
  • 查看事件参数结构（
    ChangeEventArgs
    、
    FilteringEventArgs
    等）
  • 查阅所有编程控制可用的方法
  • 了解接口模型（
    FieldSettingsModel
    、
    PopupEventArgs
    等）

Quick Start Example

快速入门示例

Installation & Setup

安装与配置

bash
npm install @syncfusion/ej2-react-dropdowns
bash
npm install @syncfusion/ej2-react-dropdowns

Basic ComboBox (Functional Component)

基础ComboBox（函数组件）

tsx
import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

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

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsList}
      placeholder="Select a sport"
      allowCustom={true}
    />
  );
}
tsx
import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

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

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsList}
      placeholder="Select a sport"
      allowCustom={true}
    />
  );
}

With Data Binding (JSON Objects)

绑定JSON对象数据

tsx
export default function App() {
  const sportsData = [
    { Id: 'game1', Game: 'Badminton', Players: 2 },
    { Id: 'game2', Game: 'Football', Players: 11 },
    { Id: 'game3', Game: 'Cricket', Players: 11 }
  ];

  const fields = { text: 'Game', value: 'Id' };

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
      change={(e) => console.log('Selected:', e.value)}
    />
  );
}
tsx
export default function App() {
  const sportsData = [
    { Id: 'game1', Game: 'Badminton', Players: 2 },
    { Id: 'game2', Game: 'Football', Players: 11 },
    { Id: 'game3', Game: 'Cricket', Players: 11 }
  ];

  const fields = { text: 'Game', value: 'Id' };

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
      change={(e) => console.log('Selected:', e.value)}
    />
  );
}

Common Patterns

常用实现模式

Pattern 1: Filtered Search for User Selection

模式1：用户选择的过滤搜索

Problem: User needs to find items in a list of 500+ entries.
Solution: Use filtering with controlled input to display only matching items. For very large datasets (5,000+ items), combine with 
enableVirtualization
and inject 
VirtualScroll
.
tsx
import { ComboBoxComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';

const [filterValue, setFilterValue] = useState('');

<ComboBoxComponent 
  dataSource={largeDataset}
  fields={{ text: 'name', value: 'id' }}
  filtering={(e) => filterByName(e, 'name')}
  change={(e) => setFilterValue(e.value)}
  allowFiltering={true}
  enableVirtualization={true}
  popupHeight="200px"
>
  <Inject services={[VirtualScroll]} />
</ComboBoxComponent>
问题： 用户需要在500+条选项的列表中查找内容。 解决方案： 结合受控输入的过滤能力仅展示匹配选项。针对超大数据集（5000+条选项），搭配
enableVirtualization
并注入
VirtualScroll
使用。
tsx
import { ComboBoxComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';

const [filterValue, setFilterValue] = useState('');

<ComboBoxComponent 
  dataSource={largeDataset}
  fields={{ text: 'name', value: 'id' }}
  filtering={(e) => filterByName(e, 'name')}
  change={(e) => setFilterValue(e.value)}
  allowFiltering={true}
  enableVirtualization={true}
  popupHeight="200px"
>
  <Inject services={[VirtualScroll]} />
</ComboBoxComponent>

Pattern 2: Grouped Categories

模式2：分类分组

Problem: Items need to be organized by type for clarity.
Solution: Use groupBy field mapping with data grouped by category.
tsx
const categorizedData = [
  { Category: 'Sports', Item: 'Cricket', value: 1 },
  { Category: 'Sports', Item: 'Football', value: 2 },
  { Category: 'Games', Item: 'Chess', value: 3 },
  { Category: 'Games', Item: 'Carrom', value: 4 }
];

const fields = { 
  text: 'Item', 
  value: 'value', 
  groupBy: 'Category' 
};

<ComboBoxComponent dataSource={categorizedData} fields={fields} />
问题： 需要按类型整理选项提升可读性。 解决方案： 使用groupBy字段映射，按分类对数据分组。
tsx
const categorizedData = [
  { Category: 'Sports', Item: 'Cricket', value: 1 },
  { Category: 'Sports', Item: 'Football', value: 2 },
  { Category: 'Games', Item: 'Chess', value: 3 },
  { Category: 'Games', Item: 'Carrom', value: 4 }
];

const fields = { 
  text: 'Item', 
  value: 'value', 
  groupBy: 'Category' 
};

<ComboBoxComponent dataSource={categorizedData} fields={fields} />

Pattern 3: Remote Data with Loading

模式3：带加载状态的远程数据

Problem: Fetch data from an API based on user search.
Solution: Use DataManager with Web API adapter.
tsx
import { DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';

const dataManager = new DataManager({
  url: 'https://api.example.com/sports',
  adaptor: new WebApiAdaptor()
});

<ComboBoxComponent 
  dataSource={dataManager}
  fields={{ text: 'name', value: 'id' }}
  allowFiltering={true}
/>
问题： 根据用户搜索内容从API拉取数据。 解决方案： 配合Web API适配器使用DataManager。
tsx
import { DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';

const dataManager = new DataManager({
  url: 'https://api.example.com/sports',
  adaptor: new WebApiAdaptor()
});

<ComboBoxComponent 
  dataSource={dataManager}
  fields={{ text: 'name', value: 'id' }}
  allowFiltering={true}
/>

Pattern 4: Custom Template for Rich Content

模式4：富内容自定义模板

Problem: Display icons or additional info with each item.
Solution: Use itemTemplate prop for custom HTML rendering.
tsx
const itemTemplate = (props) => {
  return (
    <div className="flex items-center gap-2">
      <span className={`icon icon-${props.value}`}></span>
      <span>{props.name}</span>
      <small className="text-gray-500">({props.players} players)</small>
    </div>
  );
};

<ComboBoxComponent 
  dataSource={sportsData}
  itemTemplate={itemTemplate}
  fields={{ text: 'name', value: 'id' }}
/>
问题： 每个选项需要展示图标或额外信息。 解决方案： 使用itemTemplate属性自定义HTML渲染。
tsx
const itemTemplate = (props) => {
  return (
    <div className="flex items-center gap-2">
      <span className={`icon icon-${props.value}`}></span>
      <span>{props.name}</span>
      <small className="text-gray-500">({props.players} players)</small>
    </div>
  );
};

<ComboBoxComponent 
  dataSource={sportsData}
  itemTemplate={itemTemplate}
  fields={{ text: 'name', value: 'id' }}
/>

Key Props Reference

核心属性参考

PropTypeDescriptionCommon Use
dataSource
Array|DataManagerData items to displayAll use cases
fields
FieldSettingsModelMap data fields (text, value, groupBy, iconCss, disabled)Complex data
placeholder
stringHint text when emptyUX guidance
allowCustom
booleanAllow user to enter custom values not in the list. Default: 
true
Open-ended input
allowFiltering
booleanEnable filter bar (search box) in the popup. Default: 
false
Search capability
enableVirtualization
booleanEnable virtual scrolling for large datasets. Requires 
<Inject services={[VirtualScroll]} />
. Default: 
false
Large datasets (5,000+ items)
sortOrder
SortOrder
'None'
| 
'Ascending'
| 
'Descending'
. Default: 
null
Sorted lists
popupHeight
string|numberDropdown height (e.g., 
'300px'
). Default: 
'300px'
Layout control
popupWidth
string|numberDropdown width (e.g., 
'100%'
). Default: 
'100%'
Layout control
enabled
booleanEnable/disable component. Default: 
true
Conditional rendering
readonly
booleanPrevent user input. Default: 
false
View-only mode
showClearButton
booleanShow clear (×) button. Default: 
true
Allow clearing selection
change
EmitType<ChangeEventArgs>Fires when selection changesEvent handling
filtering
EmitType<FilteringEventArgs>Fires when user types; use for custom filter logicAdvanced search
itemTemplate
Function|stringCustom item HTML for each list itemRich UI
属性名类型描述常用场景
dataSource
Array|DataManager要展示的数据源全场景通用
fields
FieldSettingsModel映射数据字段（文本、值、分组字段、图标CSS、禁用状态）复杂数据场景
placeholder
string空值时的提示文本UX引导
allowCustom
boolean允许用户输入列表外的自定义值，默认：
true
开放式输入场景
allowFiltering
boolean开启下拉框内的过滤栏（搜索框），默认：
false
搜索能力需求
enableVirtualization
boolean为大数据集开启虚拟滚动，需要搭配
<Inject services={[VirtualScroll]} />
使用，默认：
false
大数据集（5000+条选项）场景
sortOrder
SortOrder
'None'
| 
'Ascending'
| 
'Descending'
，默认：
null
排序列表场景
popupHeight
string|number下拉框高度（例如
'300px'
），默认：
'300px'
布局控制
popupWidth
string|number下拉框宽度（例如
'100%'
），默认：
'100%'
布局控制
enabled
boolean启用/禁用组件，默认：
true
条件渲染场景
readonly
boolean禁止用户输入，默认：
false
只读模式
showClearButton
boolean展示清除（×）按钮，默认：
true
允许清空选择的场景
change
EmitType<ChangeEventArgs>选中值变化时触发事件处理
filtering
EmitType<FilteringEventArgs>用户输入时触发，用于自定义过滤逻辑高级搜索场景
itemTemplate
Function|string每个列表项的自定义HTML模板富UI场景

Next Steps

后续步骤

  1. New to ComboBox? → Start with getting-started.md
  2. Need specific data? → Go to data-binding.md
  3. Performance concerns? → Check advanced-features.md
  4. Design customization? → See styling-and-theming.md
  5. Common scenarios? → Explore how-to-guide.md (autofill, cascading, icons)
  6. Resizable dropdowns? → Read popup-resizing.md
  7. Stuck? → Visit troubleshooting.md
  8. Need full API details? → See api.md for all properties, methods, events, and interface models
  1. 刚接触ComboBox？ → 从getting-started.md开始
  2. 需要对接特定数据源？ → 查看data-binding.md
  3. 有性能顾虑？ → 查阅advanced-features.md
  4. 需要自定义设计？ → 参考styling-and-theming.md
  5. 寻找常见场景实现？ → 浏览how-to-guide.md（自动填充、级联下拉、图标展示）
  6. 需要可缩放下拉框？ → 阅读popup-resizing.md
  7. 遇到问题？ → 访问troubleshooting.md
  8. 需要完整API说明？ → 查看api.md获取所有属性、方法、事件和接口模型说明