When to Use This Skill
Use this skill when you need to:
- Set up a Syncfusion JavaScript ComboBox component in your web application
- Create a dropdown for single-item selection from predefined options
- Implement filtering and search functionality as users type
- Bind ComboBox to local arrays or remote data sources (OData, Web API, DataManager)
- Group and organize list items with custom display templates
- Enable custom value entry when items aren't in the predefined list
- Configure advanced features (virtual scrolling, disabled items, resizing)
- Integrate with forms and handle value selection events
- Ensure keyboard navigation and accessibility compliance (WCAG 2.2, ARIA)
- Customize styling, themes, and support RTL languages
Skip this skill if:
- You need multi-item selection (use MultiSelect Dropdown instead)
- You need a simple select without filtering (use regular HTML select)
- You're not using TypeScript (check framework-specific documentation)
- You need a simple button dropdown (use DropdownButton instead)
Component Overview & Architecture
The ComboBox is a flexible dropdown component that allows users to:
- Select from a list of predefined options
- Enter custom values when
allowCustomis enabled - Search/filter items as they type in real-time
- Group items by category with custom headers
- Customize display with templates for items, groups, headers, and footers
Key Characteristics
| Aspect | Details |
|---|---|
| Selection Mode | Single item from predefined list OR custom value |
| Data Sources | Local arrays, remote OData, DataManager, Web API, async data |
| Filtering | Real-time search with configurable filter strategies |
| Performance | Virtual scrolling for large datasets (10,000+ items) |
| Customization | Item templates, group headers, custom CSS styling |
| Accessibility | WCAG 2.2 compliant, full keyboard navigation, ARIA attributes |
| Events | select, filtering, change, blur, focus, scroll, actionFailure |
When to Use ComboBox vs Alternatives
| Component | Use Case |
|---|---|
| ComboBox | Single selection with search/filter enabled |
| Dropdown List | Single selection, no search, fixed list |
| MultiSelect | Multiple items selection |
| AutoComplete | Search with suggestions from large dataset |
| Mention | @mentions in text input (Twitter-like) |
Documentation Navigation Guide
📄 Getting Started
Read: references/getting-started.md
- Install
@syncfusion/ej2-dropdownspackage and dependencies - Configure webpack for TypeScript bundling
- Import CSS themes (Material, Bootstrap, Fabric)
- Create HTML input element and initialize ComboBox
- Bind simple string array data
- Set basic properties (placeholder, value, popupHeight)
- Run the application and verify setup
📄 Data Binding & Sources
Read: references/data-binding.md
- Bind to local arrays of strings
- Bind to arrays of JSON objects with field mapping
- Handle nested object fields (Country.Name, Code.Id)
- Fetch data from remote OData services
- Use DataManager with Query for data filtering
- Handle dynamic data updates
- Common data binding patterns and gotchas
📄 Filtering & Search
Read: references/filtering-and-search.md
- Enable filtering with
allowFilteringproperty - Configure filter types (startsWith, contains, endsWith)
- Case-sensitive vs case-insensitive filtering
- Diacritics filtering for accent-insensitive search
- Debounce delay to optimize performance
- Minimum filter character requirements
- Custom filtering logic with filtering event
📄 Templates & Grouping
Read: references/templates-and-grouping.md
- Item templates for custom list item rendering
- Group templates for category headers
- Header and footer templates for popup decoration
- Group items by data field with
groupBy - Template syntax and interpolation patterns
- Combining multiple templates effectively
- Real-world template examples
📄 Disabled Items & Resizable Popup
Read: references/disabled-items-and-resize.md
- Mark specific items as non-selectable using disabled field
- Dynamic item disabling with disableItem() method
- Disable entire ComboBox component
- Enable user-resizable popups for better visibility
- Configure popup height and width
- Real-world examples (permissions, inventory status)
📄 Advanced Features & Configuration
Read: references/advanced-features.md
- Virtual scrolling for performance with large lists (10,000+ items)
- Custom values not in the predefined list
- Read-only mode for display-only scenarios
- Event handling (select, filtering, change, blur, actionFailure)
- RTL support for right-to-left languages
- CSS class customization and styling
- Keyboard navigation and accessibility features
- WCAG 2.2 compliance and screen reader support
📄 How-To Guides
Read: references/how-to-guides.md
- Auto-complete search functionality
- Cascading dropdowns (Country → State → City)
- Adding icons to list items
- Form integration and validation
- Custom styling and CSS customization
Quick Start Example
Minimal Setup (5 minutes)
HTML:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="node_modules/@syncfusion/ej2-base/styles/material.css" />
<link rel="stylesheet" href="node_modules/@syncfusion/ej2-dropdowns/styles/material.css" />
</head>
<body>
<input type="text" id="comboelement" />
</body>
</html>
TypeScript (app.ts):
import { ComboBox } from '@syncfusion/ej2-dropdowns';
// Define simple data array
const sportsData: string[] = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'];
// Initialize ComboBox component
const comboBoxObject: ComboBox = new ComboBox({
dataSource: sportsData,
placeholder: "Select a sport",
popupHeight: '200px'
});
// Render the component to DOM
comboBoxObject.appendTo('#comboelement');
What's happening:
- Import
ComboBoxfrom@syncfusion/ej2-dropdownspackage - Define array of strings as data source
- Create ComboBox instance with configuration object
- Set placeholder for empty state hint
- Render component to HTML element with
appendTo()
Result: A dropdown that allows users to select a sport or type custom values.
Common Patterns & Workflows
Pattern 1: Data Objects with Field Mapping
Scenario: You have an array of objects and need to display specific fields.
const employeeData: { [key: string]: Object }[] = [
{ Id: 'emp1', Name: 'Alice Johnson', Department: 'Engineering' },
{ Id: 'emp2', Name: 'Bob Smith', Department: 'Sales' },
{ Id: 'emp3', Name: 'Carol White', Department: 'Marketing' }
];
const comboBox: ComboBox = new ComboBox({
dataSource: employeeData,
fields: { text: 'Name', value: 'Id' }, // Map which field to show/store
placeholder: "Select an employee"
});
comboBox.appendTo('#comboelement');
When to use: Working with database records, API responses, or structured data.
Pattern 2: Search & Filter
Scenario: User types to search/filter the list items dynamically.
const comboBox: ComboBox = new ComboBox({
dataSource: ['California', 'Florida', 'Alaska', 'Georgia'],
allowFiltering: true, // Enable search box
placeholder: "Select a state"
});
comboBox.appendTo('#comboelement');
When to use: Large lists where users need to quickly find items.
See: Filtering & Search Reference
Pattern 3: Remote Data with Debounce
Scenario: Fetch data from server as user types, but not on every keystroke.
import { ComboBox, FilteringEventArgs } from '@syncfusion/ej2-dropdowns';
import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
const comboBox: ComboBox = new ComboBox({
dataSource: new DataManager({
url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Customers',
adaptor: new ODataV4Adaptor,
crossDomain: true
}),
query: new Query().select(['ContactName', 'CustomerID']).take(6),
fields: { text: 'ContactName', value: 'CustomerID' },
allowFiltering: true,
debounceDelay: 300, // Wait 300ms before fetching
placeholder: "Select a customer"
});
comboBox.appendTo('#comboelement');
When to use: Server-side search for scalability with large datasets.
See: Filtering & Search Reference
Pattern 4: Cascading Dropdowns
Scenario: Second ComboBox depends on first ComboBox selection.
// First ComboBox - Countries
const countryData: { [key: string]: Object }[] = [
{ id: 'USA', name: 'United States' },
{ id: 'IND', name: 'India' },
{ id: 'GBR', name: 'United Kingdom' }
];
const countryCombo: ComboBox = new ComboBox({
dataSource: countryData,
fields: { text: 'name', value: 'id' },
change: (args: any) => {
// Update second ComboBox when selection changes
const selectedCountry = args.value;
stateCombo.dataSource = getStatesForCountry(selectedCountry);
stateCombo.refresh();
},
placeholder: "Select country"
});
countryCombo.appendTo('#country');
// Second ComboBox - States (initially empty)
const stateCombo: ComboBox = new ComboBox({
dataSource: [],
placeholder: "Select state"
});
stateCombo.appendTo('#state');
function getStatesForCountry(country: string): string[] {
const stateMap: { [key: string]: string[] } = {
'USA': ['California', 'Texas', 'New York'],
'IND': ['Tamil Nadu', 'Kerala', 'Maharashtra'],
'GBR': ['England', 'Scotland', 'Wales']
};
return stateMap[country] || [];
}
When to use: Multi-level selection where options depend on previous choices.
See: Advanced Features Reference
Keyboard Navigation
The ComboBox fully supports keyboard navigation for accessibility:
| Key | Action |
|---|---|
| ↓ Arrow Down | Select next item or open popup |
| ↑ Arrow Up | Select previous item |
| Enter | Select focused item |
| Escape | Close popup |
| Tab | Move to next element (close popup) |
| Alt + ↓ | Open popup list |
| Alt + ↑ | Close popup list |
| Home | Move cursor to start of text |
| End | Move cursor to end of text |
Users can also type to filter items when popup is open.
Accessibility Features
The ComboBox meets WCAG 2.2, Section 508, and ADA compliance standards:
- ✅ ARIA Attributes:
role="combobox",aria-expanded,aria-selected,aria-disabled - ✅ Screen Reader Support: All elements labeled and announced properly
- ✅ Keyboard Navigation: Full control without mouse
- ✅ Focus Management: Clear focus indicators and tab order
- ✅ Color Contrast: Meets WCAG AA standards
- ✅ RTL Support: Automatic layout adjustment for right-to-left languages
See: Advanced Features Reference
Common Issues & Troubleshooting
Issue: CSS styles not loading?
- Ensure CSS import statement in HTML:
<link rel="stylesheet" href="node_modules/@syncfusion/ej2-dropdowns/styles/material.css" /> - Check theme name (material, bootstrap, fabric, tailwind)
Issue: ComboBox not rendering?
- Verify HTML element exists with matching ID
- Ensure
appendTo()called after ComboBox initialization - Check browser console for JavaScript errors
Issue: Data not showing?
- Verify dataSource is properly defined
- For object arrays, check field mapping (text, value match actual data)
- Use browser DevTools to inspect data structure
Issue: Filtering not working?
- Set
allowFiltering: true - For remote data, implement filtering event handler
- Check debounceDelay isn't too high (default 300ms)
Next Steps
- Start with: Getting Started to set up your first ComboBox
- Then explore: Data Binding for your specific data source
- Add features: Use Filtering or Templates as needed
- Advanced: Check Advanced Features for virtual scrolling, events, and accessibility
Resources
See Also
- AutoComplete: For search suggestions and autocomplete behavior
- MultiSelect: For multiple item selection dropdown
- Dropdown List: For simple selection without filtering
- Mention: For @mention functionality in text areas