Syncfusion React Dropdowns

Implementing Syncfusion React Dropdowns

AutoComplete

The AutoComplete component provides a matched suggestion list as the user types into an input field, allowing selection from the filtered results. It supports local and remote data, rich filtering options, templates, grouping, virtualization, and full accessibility.

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Package installation (@syncfusion/ej2-react-dropdowns)
• CSS imports and theme configuration
• Basic component setup (functional and class components)
• Binding a simple string array
• Configuring popup height and width (popupHeight, popupWidth)

Data Binding

📄 Read: references/data-binding.md

• Array of strings or numbers
• Array of objects with fields mapping (value, groupBy, iconCss)
• Array of complex/nested objects (dot-notation field mapping)
• Remote data with DataManager (ODataV4Adaptor, WebApiAdaptor)
• Using query property to filter/select remote data
• sortOrder for alphabetical ordering

Filtering

📄 Read: references/filtering.md

• Filter types: StartsWith, EndsWith, Contains
• suggestionCount – limit number of suggestions
• minLength – minimum characters before search triggers
• ignoreCase – case-sensitive filtering
• ignoreAccent – diacritics filtering
• debounceDelay – delay filtering to reduce requests
• Custom filtering with the filtering event

Grouping

📄 Read: references/grouping.md

• Grouping items using fields.groupBy
• Fixed and inline group headers
• Custom group header with groupTemplate

Templates

📄 Read: references/templates.md

• itemTemplate – customize each list item
• groupTemplate – customize group header
• headerTemplate – static popup header
• footerTemplate – static popup footer
• noRecordsTemplate – message when no data found
• actionFailureTemplate – message on remote fetch failure

Value Binding

📄 Read: references/value-binding.md

• Binding primitive values (string, number)
• Object binding with allowObjectBinding
• Presetting selected values with the value property

Virtualization

📄 Read: references/virtual-scroll.md

• enableVirtualization for large datasets
• Injecting the VirtualScroll service
• Virtual scrolling with local data, remote data, and grouping
• Customizing item count with query.take()

Disabled Items

📄 Read: references/disabled-items.md

• Disabling items via fields.disabled
• disableItem method for dynamic disabling
• Disabling the entire component with enabled={false}

Accessibility and Localization

📄 Read: references/accessibility-localization.md

• WAI-ARIA roles and attributes
• Keyboard navigation shortcuts
• RTL support (enableRtl)
• Localization with L10n (noRecordsTemplate, actionFailureTemplate text)
• WCAG 2.2 compliance overview

Styling and Customization

📄 Read: references/styling.md

• CSS class targets for wrapper, icon, focus, placeholder, selection
• Float label customization
• Popup item appearance
• cssClass property for custom class injection
• Popup resize (allowResize)
• Mandatory asterisk styling

How-To: Autofill, Highlight, and Icons

📄 Read: references/how-to.md

• autofill – suggest first matched item on Arrow Down
• highlight – highlight typed characters in suggestion list
• Icon support with fields.iconCss

API Reference

📄 Read: references/api.md

• All properties with types, defaults, and descriptions
• All methods with parameters and return types
• All events with descriptions

Quick Start Example

Installation: Pin packages to a specific major version to reduce supply-chain risk.

```bash

npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-react-inputs@^33.x.x @syncfusion/ej2-base@^33.x.x

```

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-inputs/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

const sportsData: string[] = [
  'Badminton', 'Basketball', 'Cricket', 'Football',
  'Golf', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
];

export default function App() {
  return (
    <AutoCompleteComponent
      id="sports-ac"
      dataSource={sportsData}
      placeholder="Find a game"
    />
  );
}

Common Patterns

Object data source with field mapping

const sportsData = [
  { id: 'Game1', game: 'Badminton' },
  { id: 'Game2', game: 'Basketball' },
];
const fields = { value: 'game' };

<AutoCompleteComponent dataSource={sportsData} fields={fields} placeholder="Find a game" />

Remote data binding (security-first)

Security: Do not call arbitrary third-party URLs directly from client code. Route external API calls through a trusted server-side proxy that enforces allowed endpoints, authentication, rate limits, and response validation.

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';

// Use a controlled server proxy endpoint here. Do not use public third-party URLs directly.
const customerData = new DataManager({
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
  url: 'https://your-trusted-proxy.example/api/customers'
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { value: 'ContactName' };

<AutoCompleteComponent
  dataSource={customerData}
  query={query}
  fields={fields}
  sortOrder="Ascending"
  placeholder="Find a customer" />

Filtering with custom options

<AutoCompleteComponent
  dataSource={sportsData}
  filterType="StartsWith"
  minLength={2}
  suggestionCount={5}
  debounceDelay={300}
  ignoreCase={true}
  placeholder="Type to search"
/>

Accessing methods via ref

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';
import { useRef } from 'react';

export default function App() {
  const acRef = useRef<AutoCompleteComponent>(null);

  return (
    <>
      <AutoCompleteComponent ref={acRef} dataSource={sportsData} placeholder="Find a game" />
      <button onClick={() => acRef.current?.showPopup()}>Open</button>
      <button onClick={() => acRef.current?.clear()}>Clear</button>
    </>
  );
}

ComboBox

The ComboBox component provides a dropdown input that allows users to type to filter or select from a predefined list. It supports local and remote data binding, custom values, filtering, grouping, templates, virtual scrolling, and full accessibility.

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: Pin packages to a specific major version to reduce supply-chain risk.

```bash

npm install @syncfusion/ej2-react-dropdowns@^33.x.x

```

---

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

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

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

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

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

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

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

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

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

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

API Reference

📄 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.)

---

Quick Start Example

Installation & Setup

Installation: Pin packages to a specific major version to reduce supply-chain risk.

```bash

npm install @syncfusion/ej2-react-dropdowns@^33.x.x

```

Basic ComboBox (Functional Component)

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)

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

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.

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

Problem: Items need to be organized by type for clarity. Solution: Use groupBy field mapping with data grouped by category.

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 (security-first)

Problem: Fetch data from an API based on user search.

Security-first solution: Route external API requests through a trusted server-side proxy that validates and sanitizes responses. Do not embed third‑party URLs directly in client-side code.

import { DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';

// Use your server-side proxy here. The proxy should enforce allowed upstream hosts and
// sanitize responses before returning to the client.
const dataManager = new DataManager({
  url: 'https://your-trusted-proxy.example/api/search',
  adaptor: new WebApiAdaptor()
});

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

Pattern 4: Custom Template for Rich Content

Problem: Display icons or additional info with each item. Solution: Use itemTemplate prop for custom HTML rendering.

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

---

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

DropDownList

The DropDownList component provides a list of predefined values from which users can select a single value. It supports local and remote data binding, filtering, grouping, custom templates, virtual scrolling, accessibility, and rich customization.

Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and package setup (@syncfusion/ej2-react-dropdowns)
• CSS imports with tailwind3 theme
• Basic DropDownList (functional and class components)
• Binding a data source
• Configuring popup height and width

Data Binding & Value Binding

📄 Read: references/data-binding.md

• Binding primitive arrays (strings, numbers)
• Binding JSON object arrays with fields mapping (text, value, groupBy, iconCss)
• Remote data with DataManager (OData, ODataV4, WebAPI adaptors)
• Value binding: preselecting values, binding primitive vs. complex objects
• Disabling individual items with fields.disabled

Filtering

📄 Read: references/filtering.md

• Enabling allowFiltering for search-as-you-type
• Handling the filtering event with updateData
• Preventing default filtering — always set args.preventDefaultAction = true in custom handlers
• Filter types: startswith, contains, endsWith, case-sensitive options
• Filtering by multiple fields — use Predicate with .or() to match typed text against both text and value fields (or any combination)
• Remote/server-side filtering with minimum character guard
• Diacritics filtering (ignoreAccent), debounce delay
• Highlight filtered text, custom search logic

Grouping & Templates

📄 Read: references/grouping-and-templates.md

• Grouping items with the groupBy field
• Fixed and inline group headers
• Custom group header template
• Item template, value (selected) template
• Header and footer templates
• No-records and action-failure templates

Features & Configuration

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

• Sorting (sortOrder: ascending, descending)
• Virtual scrolling for large lists (enableVirtualization)
• Popup resize (allowResize)
• Incremental search, clear button, readonly, disabled
• RTL support, Preact usage

Accessibility, Styling & Localization

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

• WCAG 2.2 / Section 508 compliance
• Keyboard navigation shortcuts
• ARIA roles and attributes
• `cssClass` prop — scoped per-instance CSS class, multiple classes, conditional classes, built-in utility classes (e-error, e-success)
• CSS class customization (wrapper, icon, popup, list items, placeholder)
• Theming (tailwind3, material3, bootstrap5, fluent2)
• Localization (L10n, noRecordsTemplate, actionFailureTemplate)
• RTL layout (enableRtl)

API Reference

📄 Read: references/api.md

• Complete properties reference with types, defaults, and usage examples
• All methods with signatures, parameters, and return types
• All events with argument interfaces and usage examples
• Interface details: FieldSettingsModel, ChangeEventArgs, SelectEventArgs, PopupEventArgs, FilteringEventArgs
• Quick-reference summary tables for properties, methods, and events

How-To Patterns

📄 Read: references/how-to.md

• Add, remove, or modify items dynamically
• Cascading (dependent) dropdowns
• Multiple cascading dropdowns
• Remote data how-to
• Close popup on scroll, tooltip on items, icons in items
• Value change event, clearing selected value

---

Quick Start Example

Installation: Pin packages to a specific major version to reduce supply-chain risk.

```bash

npm install @syncfusion/ej2-react-dropdowns@^33.x.x --save

```

// 1. See pinned install command above.

// 2. CSS in src/App.css
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
import './App.css';

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

  return (
    <DropDownListComponent
      id="ddlelement"
      dataSource={sportsData}
      placeholder="Select a game"
    />
  );
}

Common Patterns

JSON Object Data with Fields Mapping

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const countryData = [
    { Id: 'au', Country: 'Australia' },
    { Id: 'br', Country: 'Brazil' },
    { Id: 'cn', Country: 'China' },
    { Id: 'in', Country: 'India' },
  ];
  const fields = { text: 'Country', value: 'Id' };

  return (
    <DropDownListComponent
      dataSource={countryData}
      fields={fields}
      placeholder="Select a country"
    />
  );
}

Filtering (Search-as-you-type)

import { DropDownListComponent, FilteringEventArgs } from '@syncfusion/ej2-react-dropdowns';
import { Query } from '@syncfusion/ej2-data';

export default function App() {
  const searchData = [
    { Index: 's1', Country: 'Alaska' },
    { Index: 's2', Country: 'California' },
    { Index: 's3', Country: 'Florida' },
  ];
  const fields = { text: 'Country', value: 'Index' };

  function onFiltering(args: FilteringEventArgs) {
    // Local example: updateData is applied against local `searchData` below.
    // For remote filtering, route requests through a trusted server proxy and
    // validate/sanitize responses before calling `updateData`.
    args.preventDefaultAction = true; // prevent built-in filter from running alongside custom logic
    let query = new Query();
    query = args.text !== '' ? query.where('Country', 'startswith', args.text, true) : query;
    args.updateData(searchData, query);
  }

  return (
    <DropDownListComponent
      dataSource={searchData}
      fields={fields}
      allowFiltering={true}
      filtering={onFiltering}
      placeholder="Select a country"
    />
  );
}

Preselect a Value

<DropDownListComponent
  dataSource={sportsData}
  value="Cricket"
  placeholder="Select a game"
/>

Grouped Items

const vegetableData = [
  { Vegetable: 'Cabbage', Category: 'Leafy and Salad', Id: 'item1' },
  { Vegetable: 'Chickpea', Category: 'Beans', Id: 'item6' },
  { Vegetable: 'Garlic',   Category: 'Bulb and Stem', Id: 'item9' },
];
const fields = { groupBy: 'Category', text: 'Vegetable', value: 'Id' };

<DropDownListComponent dataSource={vegetableData} fields={fields} placeholder="Select a vegetable" />

Key Props

Common Use Cases

Simple static list → Pass string[] to dataSource, done.

Data from API → Use DataManager with WebApiAdaptor; read references/data-binding.md.

Search/filter as user types → Set allowFiltering={true}, handle filtering event; read references/filtering.md.

Categorized items → Map groupBy field; read references/grouping-and-templates.md.

Custom item layout → Use itemTemplate; read references/grouping-and-templates.md.

Large dataset (10k+ items) → Enable enableVirtualization + inject VirtualScroll; read references/features-and-configuration.md.

Dependent dropdowns → Reload second dropdown's dataSource on first's change event; read references/how-to.md.

ListBox

The Syncfusion ListBox component displays a list of items in a scrollable container, enabling single or multiple selection. It supports local and remote data binding, drag-and-drop reordering, filtering, grouping, custom templates, dual-list transfer, and full accessibility.

Documentation Guide

Navigate to specific topics based on your implementation needs:

Getting Started

📄 Read: references/getting-started.md

• React app setup (Vite/Create React App)
• Installing Syncfusion packages
• CSS imports and theming
• Basic ListBox component creation
• Running the application

Selection & Events

📄 Read: references/selection.md

• Single selection mode
• Multiple selection mode
• Selection events and handlers
• Programmatic selection management
• Working with selected items

Data Binding & Structure

📄 Read: references/data-binding.md

• Array and object data binding
• Text and value properties
• Data source configuration
• Grouping data
• Hierarchical data structures

Custom Templates & Icons

📄 Read: references/icons-and-templates.md

• Icon rendering in items
• Custom item templates
• HTML content rendering
• Template variables and syntax
• Conditional rendering

Advanced Features

📄 Read: references/features.md

• Drag and drop functionality
• Filtering and search
• Sorting and grouping
• Dual ListBox (transfer list)
• Scroller configuration
• Item enable/disable

Styling & Appearance

📄 Read: references/style-and-appearance.md

• CSS class customization
• Theme integration
• Styling items and groups
• Responsive design
• Custom CSS variables

Accessibility

📄 Read: references/accessibility.md

• WCAG 2.2 compliance
• Keyboard navigation
• ARIA attributes
• Screen reader support
• RTL (right-to-left) support

How-To Guides

📄 Read: references/how-to-guides.md

• Add items dynamically
• Select items programmatically
• Enable/disable items
• Filter ListBox data
• Enable scroller for long lists
• Form integration & submission

Dual ListBox (Transfer)

📄 Read: references/dual-list-box.md

• Two-way item transfer between lists
• Toolbar operations (move up/down, transfer)
• Permission and skill assignment patterns
• Custom styling and responsive design
• Capacity limits and validation

API Reference

📄 Read: references/api.md

• Complete list of all properties with types and defaults
• All public methods with parameter details and return types
• All events with full event argument interfaces
• Sub-interfaces: SelectionSettingsModel, ToolbarSettingsModel, FieldSettingsModel, SourceDestinationModel

---

Quick Start Example

Installation: Pin packages to a specific major version to reduce supply-chain risk.

```bash

npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x

```

Basic ListBox with single selection:

import { ListBoxComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import './App.css';

function App() {
  const data = [
    { text: 'JavaScript', id: '1' },
    { text: 'TypeScript', id: '2' },
    { text: 'React', id: '3' },
    { text: 'Vue', id: '4' },
    { text: 'Angular', id: '5' }
  ];

  const handleChange = (e) => {
    console.log('Selected:', e.value);
  };

  return (
    <ListBoxComponent 
      dataSource={data}
      fields={{ text: 'text', value: 'id' }}
      selectionSettings={{ mode: 'Single' }}
      change={handleChange}
    />
  );
}

export default App;

---

Common Patterns

Multiple Selection

<ListBoxComponent 
  dataSource={data}
  selectionSettings={{ mode: 'Multiple' }}
/>

Checkbox Selection

Requires injecting `CheckBoxSelection` service.

import { ListBoxComponent, SelectionSettingsModel, Inject, CheckBoxSelection } from '@syncfusion/ej2-react-dropdowns';

const selectionSettings: SelectionSettingsModel = { showCheckbox: true };

<ListBoxComponent dataSource={data} selectionSettings={selectionSettings}>
  <Inject services={[CheckBoxSelection]} />
</ListBoxComponent>

With Search/Filter

<ListBoxComponent 
  dataSource={data}
  allowFiltering={true}
  filterBarPlaceholder="Search items"
/>

Custom Item Template

const itemTemplate = (props) => {
  return (
    <div>
      <span className="icon">{props.icon}</span>
      <span>{props.text}</span>
    </div>
  );
}

<ListBoxComponent 
  dataSource={data}
  itemTemplate={itemTemplate}
/>

Grouping Items

<ListBoxComponent 
  dataSource={groupedData}
  fields={{ text: 'text', groupBy: 'category' }}
/>

---

Key Props & Configuration

---

Common Use Cases

1. Select Framework - Single selection from framework list with icons 2. Multi-Select Languages - Multiple selection with search filter 3. Skill Picker - Custom templates with badges and descriptions 4. Drag-Drop Transfer - Dual ListBox for moving items between lists 5. Grouped Categories - Organizing items by category with group headers 6. Searchable Item List - Large list with filter functionality 7. Accessible Menu - Full keyboard navigation and screen reader support

---

Next Steps

1. Start with Getting Started for initial setup 2. Choose your use case (selection mode, templates, features) 3. Read relevant reference for implementation details 4. Copy code examples and customize for your needs 5. Use Accessibility guide for WCAG compliance

Need help? Each reference file contains examples, edge cases, and troubleshooting tips.

Mention

The Mention Component attaches to a target editable element (e.g. a <div contenteditable>) and displays a suggestion popup when the user types a trigger character (default @). Selecting an item inserts it inline into the editor.

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and package setup (@syncfusion/ej2-react-dropdowns)
• CSS theme imports
• Basic MentionComponent setup with target prop
• Binding a simple data source
• Custom trigger character (mentionChar) and showMentionChar

⚠️ Security Note: Installing npm packages (@syncfusion/ej2-react-dropdowns and related) must be a deliberate, user-confirmed step. Do not allow automated agents to run npm install without explicit user approval, as this introduces supply-chain risk.

Working with Data

📄 Read: references/working-with-data.md

• Binding array of strings, JSON objects, and complex nested data
• Mapping fields (text, value, groupBy, iconCss)
• Remote data with OData V4 (ODataV4Adaptor)
• Remote data with Web API (WebApiAdaptor)
• Using query to filter/select remote fields

Filtering Data

📄 Read: references/filtering-data.md

• Setting minimum filter character length (minLength)
• Changing filter type: Contains, StartsWith, EndsWith
• Allowing spaces within search text (allowSpaces)
• Customizing the suggestion count (suggestionCount)
• Debounce delay for filtering (debounceDelay)

Templates

📄 Read: references/template.md

• Item template (itemTemplate) for custom list rendering
• Display template (displayTemplate) for selected value format
• No-records template (noRecordsTemplate)
• Spinner/loading template (spinnerTemplate)
• Group header template (groupTemplate)

Customization

📄 Read: references/customization.md

• Show/hide mention character in output (showMentionChar)
• Appending suffix text after selection (suffixText)
• Configuring popup height and width (popupHeight, popupWidth)
• Custom trigger character (mentionChar)
• Leading space requirement (requireLeadingSpace)
• CSS class customization (cssClass)
• Highlight matched characters (highlight)
• Ignore accent/case in search (ignoreAccent, ignoreCase)
• Z-index for popup (zIndex)

Sorting

📄 Read: references/sorting.md

• Sorting suggestion list: Ascending, Descending, None

Disabled Items

📄 Read: references/disabled-items.md

• Disabling items via fields.disabled
• Dynamically disabling items with disableItem() method

Accessibility

📄 Read: references/accessibility.md

• WAI-ARIA attributes (aria-selected, aria-activedescendent, aria-owns)
• Keyboard navigation shortcuts
• WCAG 2.2 and Section 508 compliance
• RTL support (enableRtl)

Localization

📄 Read: references/localization.md

• Localizing the noRecordsTemplate text via L10n
• Setting locale property

API Reference

📄 Read: references/api.md

• All properties, methods, and events
• target, dataSource, fields, mentionChar, minLength, suggestionCount
• Methods: addItem, disableItem, getDataByValue, getItems, showPopup, hidePopup, search, destroy
• Events: select, change, filtering, beforeOpen, opened, closed, dataBound, actionBegin, actionComplete, actionFailure

Quick Start Example

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

// CSS imports
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

function App() {
  const mentionTarget = '#commentBox';
  const users = [
    { Name: 'Selma Rose', EmailId: 'selma@example.com' },
    { Name: 'Robert', EmailId: 'robert@example.com' },
    { Name: 'William', EmailId: 'william@example.com' },
  ];
  const fields = { text: 'Name' };

  return (
    <div>
      <label>Comments</label>
      <div id="commentBox" placeholder="Type @ to mention a user"></div>
      <MentionComponent
        target={mentionTarget}
        dataSource={users}
        fields={fields}
      />
    </div>
  );
}

export default App;

Common Patterns

Custom Trigger Character

Use mentionChar to trigger with # instead of @:

<MentionComponent
  target="#editor"
  dataSource={tags}
  mentionChar="#"
  showMentionChar={true}
/>

Remote Data with Filtering (security-first)

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';

// SECURITY: Do not call third-party endpoints from the browser. Use a server-side
// proxy that you control and that validates/sanitizes upstream responses.
const dataSource = new DataManager({
  url: 'https://your-trusted-proxy.example/api/mentions',
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { text: 'ContactName', value: 'CustomerID' };

<MentionComponent
  target="#editor"
  dataSource={dataSource}
  fields={fields}
  query={query}
  minLength={2}
  popupWidth="250px" />

Handling Selection Events

import { SelectEventArgs } from '@syncfusion/ej2-react-dropdowns';

function onSelect(args: SelectEventArgs) {
  console.log('Selected item:', args.itemData);
  console.log('Selected text:', args.text);
}

<MentionComponent
  target="#editor"
  dataSource={users}
  fields={{ text: 'Name' }}
  select={onSelect}
/>

Popup Configuration

<MentionComponent
  target="#editor"
  dataSource={data}
  fields={{ text: 'Name' }}
  popupHeight="200px"
  popupWidth="300px"
  suggestionCount={10}
  sortOrder="Ascending"
  suffixText="&nbsp;"
/>

Key Props Summary

MultiSelect

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

Component Overview

Installation: Pin packages to a specific major version to reduce supply-chain risk.

```bash

npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x @syncfusion/ej2-buttons@^33.x.x @syncfusion/ej2-inputs@^33.x.x

```

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
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]} />)

Quick Start Example

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:

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

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

Grouping

📄 Read: references/grouping.md

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

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

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

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)

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

API Reference

📄 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

Key Props Reference

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.

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

MultiColumn ComboBox

The Syncfusion MultiColumnComboBoxComponent renders a combo box with a multi-column popup grid, enabling users to select from structured tabular data. It supports local and remote data, filtering, sorting, grouping, templates, virtualization, and full accessibility compliance.

Package: @syncfusion/ej2-react-multicolumn-combobox

Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and package setup
• CSS imports and theme configuration (Tailwind 3)
• Rendering the first MultiColumnComboBoxComponent
• Binding dataSource, fields, and columns with ColumnDirective
• Configuring popupHeight and popupWidth
• Minimal working example (functional and class components)

Columns

📄 Read: references/columns.md

• Defining columns with ColumnDirective and ColumnsDirective
• field, header, width — core column properties
• textAlign for column text alignment
• template for cell-level custom rendering
• displayAsCheckBox for boolean columns
• customAttributes for column CSS customization
• headerTemplate for custom column headers
• format for data formatting

Data Binding

📄 Read: references/data-binding.md

• Binding local object arrays via dataSource
• Remote data binding with DataManager and WebApiAdaptor
• Mapping fields (text, value, groupBy)
• Using query property for filtered/limited data sets
• OData, OData V4, Web API adaptor patterns

Filtering

📄 Read: references/filtering.md

• Enabling/disabling filtering with allowFiltering
• Changing filter mode with filterType (StartsWith, EndsWith, Contains)
• filtering event for custom filter logic
• Disabling filtering for read-only scenarios

Sorting

📄 Read: references/sorting.md

• Enabling sorting with allowSorting
• Setting initial sort order with sortOrder (None, Ascending, Descending)
• Sorting multiple columns with sortType (OneColumn, MultipleColumns)
• Clicking column headers to toggle sort direction

Grouping

📄 Read: references/grouping.md

• Grouping data with fields.groupBy
• Fixed group headers in popup
• Using groupTemplate to customize group headers

Templates

📄 Read: references/templates.md

• itemTemplate for customizing each row
• headerTemplate (on ColumnDirective) for custom column headers
• groupTemplate for group header customization
• footerTemplate for popup footer content
• noRecordsTemplate for empty state display
• actionFailureTemplate for remote fetch error state

Items and Configuration

📄 Read: references/items.md

• Setting initial selection with text, value, index
• placeholder and floatLabelType for input label behavior
• showClearButton to allow clearing selection
• disabled and readonly states
• width, popupWidth, popupHeight for sizing
• cssClass for custom styling
• htmlAttributes for additional HTML attributes
• gridSettings for grid lines, row height, and alternate rows
• query for data constraints
• addItems method, focusIn, focusOut, showPopup, hidePopup

Virtualization

📄 Read: references/virtualization.md

• Enabling enableVirtualization for large datasets
• Virtual scrolling with local and remote data
• Combining with gridSettings.rowHeight

Events

📄 Read: references/events.md

• change — fired when value changes or item is selected
• select — fired on item selection
• open / close — popup open/close lifecycle
• filtering — fired on character input for custom filtering
• actionBegin / actionComplete / actionFailure — data fetch lifecycle

API Reference

📄 Read: references/api.md

• Complete list of all properties with types and defaults
• All events with their argument types
• All methods: addItems, focusIn, focusOut, getDataByValue, getItems, showPopup, hidePopup
• ColumnModel properties
• GridSettingsModel properties
• FieldSettingsModel properties

Accessibility

📄 Read: references/accessibility.md

• WCAG 2.2 and Section 508 compliance
• WAI-ARIA attributes (role, aria-expanded, aria-selected, etc.)
• Keyboard navigation shortcuts
• RTL support with enableRtl
• Screen reader support

Localization

📄 Read: references/localization.md

• Localizing noRecordsTemplate text using L10n
• Setting locale property for culture-specific rendering
• Loading translation objects

Quick Start

import { MultiColumnComboBoxComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-multicolumn-combobox';
import * as React from 'react';
import './App.css';

// CSS in App.css:
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-grids/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-multicolumn-combobox/styles/tailwind3.css";

function App() {
  const empData = [
    { EmpID: 1001, Name: 'Andrew Fuller', Designation: 'Team Lead', Country: 'England' },
    { EmpID: 1002, Name: 'Robert', Designation: 'Developer', Country: 'USA' },
    { EmpID: 1003, Name: 'Michael', Designation: 'HR', Country: 'Russia' },
  ];
  const fields = { text: 'Name', value: 'EmpID' };

  return (
    <MultiColumnComboBoxComponent
      id="multicolumn"
      dataSource={empData}
      fields={fields}
      placeholder="Select an employee"
    >
      <ColumnsDirective>
        <ColumnDirective field='EmpID' header='Employee ID' width={120} />
        <ColumnDirective field='Name' header='Name' width={120} />
        <ColumnDirective field='Designation' header='Designation' width={120} />
        <ColumnDirective field='Country' header='Country' width={100} />
      </ColumnsDirective>
    </MultiColumnComboBoxComponent>
  );
}
export default App;

Common Patterns

Pre-select an item by text

<MultiColumnComboBoxComponent dataSource={empData} fields={fields} text="Michael">
  {/* columns */}
</MultiColumnComboBoxComponent>

Enable filtering with Contains mode

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowFiltering={true}
  filterType="Contains"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

Enable sorting (descending) with multi-column support

import { SortOrder } from '@syncfusion/ej2-react-multicolumn-combobox';

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowSorting={true}
  sortOrder={SortOrder.Descending}
  sortType="MultipleColumns"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

Handle value change event

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  change={(args) => console.log('Selected:', args.value)}
>
  {/* columns */}
</MultiColumnComboBoxComponent>

Accessibility and Localization – Syncfusion React AutoComplete

Table of Contents

• Accessibility Compliance
• WAI-ARIA Attributes
• Keyboard Navigation
• RTL Support
• Localization

---

Accessibility Compliance

The AutoComplete is designed against WAI-ARIA specifications and meets the following standards:

---

WAI-ARIA Attributes

The AutoComplete applies the following ARIA attributes automatically:

---

Keyboard Navigation

---

RTL Support

Enable right-to-left rendering with enableRtl:

<AutoCompleteComponent
  id="atcelement"
  dataSource={sportsData}
  enableRtl={true}
  placeholder="Find a game"
/>

---

Localization

Use the L10n class from @syncfusion/ej2-base to localize the component's built-in strings:

Example: French localization

import { L10n } from '@syncfusion/ej2-base';
import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const customerData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });
  const fields: object = { value: 'ContactName' };
  // take(0) to trigger noRecordsTemplate
  const query: Query = new Query().select(['ContactName', 'CustomerID']).take(0);

  React.useEffect(() => {
    L10n.load({
      'fr-BE': {
        dropdowns: {
          noRecordsTemplate: 'Aucun enregistrement trouvé',
          actionFailureTemplate: "Modèle d'échec d'action",
        }
      }
    });
  }, []);

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={customerData}
      fields={fields}
      query={query}
      locale="fr-BE"
      placeholder="Trouver un client"
    />
  );
}

Call L10n.load() before the component renders (e.g., inside useEffect or componentWillMount). The locale prop on the component then activates the loaded culture.

API Reference – Syncfusion React AutoComplete

Source: https://ej2.syncfusion.com/react/documentation/api/auto-complete/index-default

Table of Contents

• Properties
• Methods
• Events

---

Properties

actionFailureTemplate

string | Function — Default: 'Request failed'

Template assigned to the popup list content when the remote data fetch request fails.

---

allowCustom

boolean — Default: true

Specifies whether the component allows a user-defined value that does not exist in the data source.

---

allowObjectBinding

boolean — Default: false

Defines whether object binding is allowed. When true, the value property holds the full selected object rather than a scalar value.

---

allowResize

boolean — Default: false

When true, a resize handle appears in the bottom-right corner of the popup, allowing users to resize width and height.

---

autofill

boolean — Default: false

When true, the first matched item is suggested inline in the input while typing. No action occurs when no matches are found.

---

cssClass

string — Default: null

Sets CSS classes on the root element for appearance customization.

---

dataSource

{ [key: string]: Object }[] | DataManager | string[] | number[] | boolean[] — Default: []

Accepts list items from local or remote sources. Can be a string array, number array, object array, or a DataManager instance.

---

debounceDelay

number — Default: 300

Delay in milliseconds before the filter operation fires after each keystroke. Set to 0 to disable debounce.

---

enablePersistence

boolean — Default: false

When true, the component state (value) is persisted across page reloads.

---

enableRtl

boolean — Default: false

When true, renders the component in right-to-left direction.

---

enableVirtualization

boolean — Default: false

When true, enables virtual scrolling. Only visible DOM elements are rendered; they are recycled as the user scrolls. Requires <Inject services={[VirtualScroll]} />.

---

enabled

boolean — Default: true

When false, the component is disabled and all user interactions are blocked.

---

fields

FieldSettingsModel — Default: { value: null, iconCss: null, groupBy: null }

Maps data table columns to component fields:

• value — Column whose value is shown in the input on selection
• iconCss — Column whose value is used as an icon CSS class
• groupBy — Column used to group items into categories
• disabled — Column that disables specific items when true
• text — Column for item display text (if different from value)

---

filterType

FilterType — Default: 'Contains'

Determines the filter strategy:

• 'StartsWith' — Items beginning with typed characters
• 'EndsWith' — Items ending with typed characters
• 'Contains' — Items containing typed characters anywhere

---

floatLabelType

FloatLabelType — Default: 'Never'

Controls float label behavior:

• 'Never' — Label never floats
• 'Always' — Label always floats above input
• 'Auto' — Label floats when input is focused or has a value

---

footerTemplate

string | Function — Default: null

Template for the static footer element at the bottom of the popup list.

---

groupTemplate

string | Function — Default: null

Template for group header labels in the popup list.

---

headerTemplate

string | Function — Default: null

Template for the static header element at the top of the popup list.

---

highlight

boolean — Default: false

When true, highlights the typed characters within suggestion list items using the e-highlight CSS class.

---

htmlAttributes

{ [key: string]: string } — Default: {}

Additional HTML attributes (e.g., title, name, maxlength) applied to the component input element.

---

ignoreAccent

boolean — Default: false

When true, diacritic characters (accents) are ignored during filtering.

---

ignoreCase

boolean — Default: true

When true (default), filtering is case-insensitive. Set to false for case-sensitive filtering.

---

isDeviceFullScreen

boolean — Default: true

When true, the popup opens in full-screen mode on mobile devices. Set to false for consistent behavior across desktop and mobile.

---

itemTemplate

string | Function — Default: null

Template for rendering each individual list item in the popup.

---

locale

string — Default: 'en-US'

Overrides the global culture and localization for this component. Use with L10n.load() to provide translations.

---

minLength

number — Default: 1

Minimum number of characters the user must type before the filter/search action fires.

---

noRecordsTemplate

string | Function — Default: 'No records found'

Template shown when no matching items are found in the suggestion list.

---

placeholder

string — Default: null

Short hint text displayed inside the input when it is empty.

---

popupHeight

string | number — Default: '300px'

Height of the suggestion popup list.

---

popupWidth

string | number — Default: '100%'

Width of the suggestion popup list. Defaults to the width of the input component.

---

query

Query — Default: null

An external Query instance that is executed along with data processing. Used to filter, select, or limit remote data.

---

readonly

boolean — Default: false

When true, user interactions (typing/selecting) are disabled but the component remains focusable.

---

showClearButton

boolean — Default: true

When true, shows a clear (×) button. Clicking it resets value, text, and index to null.

---

showPopupButton

boolean — Default: false

When true, shows a dropdown toggle button on the right side of the input.

---

sortOrder

SortOrder — Default: null

Sorts the data source:

• 'None' — No sorting
• 'Ascending' — A to Z
• 'Descending' — Z to A

---

suggestionCount

number — Default: 20

Maximum number of items shown in the suggestion popup at a time.

---

value

number | string | boolean | object | null — Default: null

Gets or sets the selected value. When allowObjectBinding is true, accepts and returns a full object.

---

width

string | number — Default: '100%'

Width of the component input element.

---

zIndex

number — Default: 1000

z-index of the popup element.

---

Methods

addItem

Adds a new item to the popup list. By default appended at the end; use itemIndex to insert at a specific position.

autocomplete.addItem({ id: 'Game9', game: 'Tennis' });
autocomplete.addItem({ id: 'Game0', game: 'Archery' }, 0); // insert at index 0

Returns: void

---

clear

Clears the selected value from the component.

autocomplete.clear();

Returns: void

---

destroy

Removes the component from the DOM and detaches all event handlers, attributes, and classes.

autocomplete.destroy();

Returns: void

---

disableItem

Disables a specific item in the popup. If the selected item is disabled, the selection is cleared.

autocomplete.disableItem('Tennis');           // by value string
autocomplete.disableItem(liElement);          // by HTMLLIElement

Returns: void

---

filter

Filters the data from the given data source using a query.

autocomplete.filter(dataSource, query, fields);

Returns: void

---

focusIn

Sets focus on the component input.

autocomplete.focusIn();

Returns: void

---

focusOut

Removes focus from the component input.

autocomplete.focusOut();

Returns: void

---

getDataByValue

Returns the data object that matches the given value.

const item = autocomplete.getDataByValue('Tennis');

Returns: { [key: string]: Object } | string | number | boolean

---

getItems

Returns all list item DOM elements currently bound to the component.

const items = autocomplete.getItems();
console.log(items.length);

Returns: Element[]

---

hidePopup

Closes the suggestion popup if it is open.

autocomplete.hidePopup();

Returns: void

---

hideSpinner

Hides the loading spinner.

autocomplete.hideSpinner();

Returns: void

---

showPopup

Opens the suggestion popup and shows matching items for the current input value.

autocomplete.showPopup();

Returns: void

---

showSpinner

Shows the loading spinner.

autocomplete.showSpinner();

Returns: void

---

Events

actionBegin

EmitType<Object>

Fires before data is fetched from a remote server.

---

actionComplete

EmitType<Object>

Fires after data is successfully fetched from a remote server.

---

actionFailure

EmitType<Object>

Fires when the remote data fetch request fails.

---

beforeOpen

EmitType<Object>

Fires before the popup opens.

---

blur

EmitType<Object>

Fires when focus moves out of the component.

---

change

EmitType<ChangeEventArgs>

Fires when an item is selected from the popup or when the model value changes. Use this event for cascading scenarios.

---

close

EmitType<PopupEventArgs>

Fires when the popup is closed.

---

created

EmitType<Object>

Fires when the component is created.

---

customValueSpecifier

EmitType<CustomValueSpecifierEventArgs>

Fires when a custom value (not in the data source) is set. Relevant when allowCustom={true}.

---

dataBound

EmitType<Object>

Fires when the data source is populated in the popup list.

---

destroyed

EmitType<Object>

Fires when the component is destroyed.

---

filtering

EmitType<FilteringEventArgs>

Fires on every character typed in the component (subject to debounceDelay). Use args.updateData() to provide custom filtered results.

---

focus

EmitType<Object>

Fires when the component gains focus.

---

open

EmitType<PopupEventArgs>

Fires when the popup opens.

---

resizeStart

EmitType<Object>

Fires when the user starts resizing the popup (requires allowResize={true}).

---

resizeStop

EmitType<Object>

Fires when the user finishes resizing the popup.

---

resizing

EmitType<Object>

Fires continuously while the popup is being resized. Provides live width and height updates.

---

select

EmitType<SelectEventArgs>

Fires when the user selects an item from the popup via mouse, tap, or keyboard navigation.

Data Binding – Syncfusion React AutoComplete

Table of Contents

• Field Mapping Overview
• Array of Strings
• Array of Objects
• Complex/Nested Object Arrays
• Remote Data with DataManager
• Sorting Bound Data

---

Field Mapping Overview

When binding objects to AutoComplete, map data columns using the fields property:

When binding complex data, always map fields correctly; otherwise the selected item will be undefined.

---

Array of Strings

The simplest form — pass a string[] directly to dataSource:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

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

  return (
    <AutoCompleteComponent id="atcelement" dataSource={sportsData} placeholder="Find a game" />
  );
}

---

Array of Objects

Pass an object array and map the display column to fields.value:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const sportsData: { [key: string]: Object }[] = [
    { id: 'Game1', game: 'Badminton' },
    { id: 'Game2', game: 'Basketball' },
    { id: 'Game3', game: 'Cricket' },
    { id: 'Game4', game: 'Football' },
    { id: 'Game5', game: 'Golf' },
    { id: 'Game6', game: 'Hockey' },
    { id: 'Game7', game: 'Rugby' },
    { id: 'Game8', game: 'Snooker' }
  ];

  const fields: object = { value: 'game' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={sportsData}
      fields={fields}
      placeholder="Find a game"
    />
  );
}

---

Complex/Nested Object Arrays

Use dot-notation in the value field to access nested properties:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const countriesData: { [key: string]: Object }[] = [
    { Country: { Name: 'Australia' }, Code: { Id: 'AU' } },
    { Country: { Name: 'Bermuda' }, Code: { Id: 'BM' } },
    { Country: { Name: 'Canada' }, Code: { Id: 'CA' } },
    { Country: { Name: 'Denmark' }, Code: { Id: 'DK' } },
    { Country: { Name: 'France' }, Code: { Id: 'FR' } },
    { Country: { Name: 'Germany' }, Code: { Id: 'DE' } },
    { Country: { Name: 'India' }, Code: { Id: 'IN' } },
    { Country: { Name: 'Japan' }, Code: { Id: 'JP' } },
  ];

  // Dot notation maps the nested "Country.Name" path
  const fields: object = { value: 'Country.Name' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={countriesData}
      fields={fields}
      placeholder="Find a country"
    />
  );
}

---

Remote Data with DataManager

Use DataManager with an adaptor to load data from a remote service. The query property controls what data is fetched:

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const customerData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });

  const query: Query = new Query()
    .from('Customers')
    .select(['ContactName', 'CustomerID'])
    .take(6);

  const fields: object = { value: 'ContactName' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={customerData}
      query={query}
      fields={fields}
      sortOrder="Ascending"
      placeholder="Find a customer"
    />
  );
}

Supported adaptors: ODataAdaptor, ODataV4Adaptor, WebApiAdaptor, UrlAdaptor, JsonAdaptor

Use the query property to select specific columns, apply filters, or limit the result set. Without a query, all records are fetched.

---

Sorting Bound Data

Use sortOrder to sort the suggestion list alphabetically:

<AutoCompleteComponent
  dataSource={customerData}
  fields={{ value: 'ContactName' }}
  sortOrder="Ascending"   // 'None' | 'Ascending' | 'Descending'
  placeholder="Find a customer"
/>

Disabled Items – Syncfusion React AutoComplete

The AutoComplete supports disabling individual items so they appear in the list but cannot be selected, as well as disabling the entire component.

---

Disabling Items via fields.disabled

Map a boolean column in the data source to fields.disabled. Items where this column is true will appear greyed out and be unselectable:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const statusData: { [key: string]: Object }[] = [
    { Status: 'Open',                 State: false },
    { Status: 'Waiting for Customer', State: false },
    { Status: 'On Hold',              State: true  },  // disabled
    { Status: 'Follow-up',            State: false },
    { Status: 'Closed',               State: true  },  // disabled
    { Status: 'Solved',               State: false },
    { Status: 'Feature Request',      State: false },
  ];

  const fields: object = { value: 'Status', disabled: 'State' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={statusData}
      fields={fields}
      placeholder="Select a status"
    />
  );
}

---

Disabling Items Dynamically via disableItem Method

Use the disableItem method to disable a specific item at runtime. The method accepts the item value, an HTML <li> element reference, or an index:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';
import { useRef } from 'react';

export default function App() {
  const acRef = useRef<AutoCompleteComponent>(null);

  const statusData: { [key: string]: Object }[] = [
    { Status: 'Open',         State: false },
    { Status: 'On Hold',      State: false },
    { Status: 'Closed',       State: false },
    { Status: 'Solved',       State: false },
  ];
  const fields: object = { value: 'Status' };

  function disableOnHold() {
    // Disable by value string
    acRef.current?.disableItem('On Hold');
  }

  return (
    <>
      <AutoCompleteComponent
        ref={acRef}
        id="atcelement"
        dataSource={statusData}
        fields={fields}
        placeholder="Select a status"
      />
      <button onClick={disableOnHold}>Disable "On Hold"</button>
    </>
  );
}

disableItem parameter options:

If the currently selected item is disabled dynamically, the selection is cleared automatically.

To disable multiple items, iterate disableItem over an array of values.

---

Disabling the Entire Component

Set enabled={false} to prevent all user interaction with the component:

<AutoCompleteComponent
  id="atcelement"
  dataSource={statusData}
  fields={fields}
  enabled={false}
  placeholder="Select a status"
/>

Filtering – Syncfusion React AutoComplete

Table of Contents

• Filter Types
• Suggestion Count
• Minimum Filter Character Length
• Case Sensitive Filtering
• Diacritics Filtering
• Debounce Delay
• Custom Filtering with the filtering Event

---

Filter Types

Control how suggestion matching works via filterType. Default is 'Contains'.

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const searchData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });
  const query: Query = new Query().from('Suppliers').select(['SupplierID', 'ContactName']).take(10);
  const fields: object = { value: 'ContactName' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={searchData}
      query={query}
      fields={fields}
      filterType="StartsWith"
      sortOrder="Ascending"
      placeholder="Find a supplier"
    />
  );
}

---

Suggestion Count

Limit the number of items shown in the suggestion popup using suggestionCount. Default is 20.

<AutoCompleteComponent
  id="atcelement"
  dataSource={customerData}
  query={query}
  fields={{ value: 'ContactName' }}
  suggestionCount={5}
  filterType="StartsWith"
  sortOrder="Ascending"
  placeholder="Find a customer"
/>

---

Minimum Filter Character Length

Set the minimum number of characters the user must type before filtering begins via minLength. Default is 1.

Useful for remote data to avoid triggering requests on every single character:

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const searchData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });
  const query: Query = new Query().select(['ContactName', 'CustomerID']).take(10);
  const fields: object = { value: 'ContactName' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={searchData}
      query={query}
      fields={fields}
      filterType="StartsWith"
      sortOrder="Ascending"
      minLength={3}
      placeholder="Type at least 3 chars"
    />
  );
}

---

Case Sensitive Filtering

By default ignoreCase is true (case-insensitive). Set ignoreCase={false} to make filtering case-sensitive:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const searchData: string[] = ['ram', 'Ravi', 'suresh', 'Suresh'];

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={searchData}
      filterType="StartsWith"
      ignoreCase={false}
      placeholder="e.g. Ravi"
    />
  );
}

With ignoreCase={false}, typing "r" will match "ram" but not "Ravi".

---

Diacritics Filtering

Enable ignoreAccent={true} to ignore diacritic characters (accents) during filtering. This helps users search international character lists without typing the exact accented character:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const diacriticsData: string[] = [
    'Aeróbics', 'Aeróbics en Agua', 'Aerografía', 'Aeromodelaje',
    'Águilas', 'Ajedrez', 'Ala Delta', 'Álbumes de Música'
  ];

  return (
    <AutoCompleteComponent
      id="diacritics"
      dataSource={diacriticsData}
      ignoreAccent={true}
      placeholder="e.g. aero"
    />
  );
}

With ignoreAccent={true}, typing "aero" will match "Aeróbics", "Aerografía", etc.

---

Debounce Delay

Use debounceDelay to set a millisecond delay before the filter action fires. Default is 300ms. Set to 0 to disable debounce entirely:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

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

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={sportsData}
      debounceDelay={500}     // Wait 500ms after user stops typing
      placeholder="Find a game"
    />
  );
}

---

Custom Filtering with the filtering Event

Use the filtering event to implement custom filter logic, such as sending custom server-side queries:

import { AutoCompleteComponent, FilteringEventArgs } from '@syncfusion/ej2-react-dropdowns';
import { DataManager, Query, ODataV4Adaptor } from '@syncfusion/ej2-data';
import * as React from 'react';

export default function App() {
  const remoteData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });

  function onFiltering(args: FilteringEventArgs) {
    // Build a custom query based on user input
    const query = new Query()
      .from('Customers')
      .select(['ContactName', 'CustomerID'])
      .where('ContactName', 'startswith', args.text, true)
      .take(10);
    args.updateData(remoteData, query);
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={remoteData}
      fields={{ value: 'ContactName' }}
      filtering={onFiltering}
      placeholder="Find a customer"
    />
  );
}

The filtering event fires on every keystroke (subject to debounceDelay). Call args.updateData(dataSource, query) to provide filtered results.

Getting Started – Syncfusion React AutoComplete

Table of Contents

• Installation
• CSS Imports
• Basic Component Setup
• Binding a Data Source
• Configuring the Popup

---

Installation

Install the Syncfusion React Dropdowns package which contains the AutoComplete component:

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

Create a new Vite React project if needed:

npm create vite@latest my-app -- --template react-ts
cd my-app
npm run dev

---

CSS Imports

Add the required CSS imports to your src/App.css file. Use the theme that matches your project (e.g., tailwind3, material, bootstrap5):

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-inputs/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

Then import App.css in src/App.tsx:

import './App.css';

---

Basic Component Setup

Functional Component

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';
import './App.css';

export default function App() {
  return (
    <AutoCompleteComponent id="atcelement" />
  );
}

Class Component

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';
import './App.css';

export default class App extends React.Component<{}, {}> {
  public render() {
    return (
      <AutoCompleteComponent id="atcelement" />
    );
  }
}

---

Binding a Data Source

After initialization, pass data using the dataSource property. The simplest form is an array of strings:

Functional Component

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

export default function App() {
  const sportsData: string[] = [
    'Badminton', 'Basketball', 'Cricket', 'Football',
    'Golf', 'Gymnastics', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
  ];

  return (
    <AutoCompleteComponent id="atcelement" dataSource={sportsData} placeholder="Find a game" />
  );
}

Class Component

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

export default class App extends React.Component<{}, {}> {
  private sportsData: string[] = [
    'Badminton', 'Basketball', 'Cricket', 'Football',
    'Golf', 'Gymnastics', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
  ];

  public render() {
    return (
      <AutoCompleteComponent id="atcelement" dataSource={this.sportsData} placeholder="Find a game" />
    );
  }
}

---

Configuring the Popup

By default, the popup width adjusts to the input element width and the popup height is 300px. Customize with popupHeight and popupWidth:

<AutoCompleteComponent
  id="atcelement"
  dataSource={sportsData}
  popupHeight="250px"
  popupWidth="250px"
  placeholder="Find a game"
/>

Grouping – Syncfusion React AutoComplete

The AutoComplete supports grouping list items into categories using the groupBy field. The group header appears both as an inline header within the list and as a fixed floating header that updates dynamically when scrolling.

---

Basic Grouping

Map the groupBy field in the fields property to the column that defines the category:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const vegetableData: { [key: string]: Object }[] = [
    { Vegetable: 'Cabbage',    Category: 'Leafy and Salad', Id: 'item1' },
    { Vegetable: 'Spinach',    Category: 'Leafy and Salad', Id: 'item2' },
    { Vegetable: 'Wheat grass',Category: 'Leafy and Salad', Id: 'item3' },
    { Vegetable: 'Yarrow',     Category: 'Leafy and Salad', Id: 'item4' },
    { Vegetable: 'Pumpkins',   Category: 'Leafy and Salad', Id: 'item5' },
    { Vegetable: 'Chickpea',   Category: 'Beans', Id: 'item6' },
    { Vegetable: 'Green bean', Category: 'Beans', Id: 'item7' },
    { Vegetable: 'Horse gram', Category: 'Beans', Id: 'item8' },
  ];

  // groupBy maps the category column; value maps the display text
  const fields: object = { groupBy: 'Category', value: 'Vegetable' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={vegetableData}
      fields={fields}
      placeholder="Select a vegetable"
    />
  );
}

---

Custom Group Header with groupTemplate

Customize the group header rendered between groups using the groupTemplate property:

import { DataManager, ODataV4Adaptor, Predicate, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const employeeData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });

  const groupPredicate = new Predicate('City', 'equal', 'london')
    .or('City', 'equal', 'seattle');

  const query: Query = new Query()
    .from('Employees')
    .select(['FirstName', 'City', 'EmployeeID'])
    .take(6)
    .where(groupPredicate);

  const fields: object = { value: 'FirstName', groupBy: 'City' };

  // Renders a bold city name as the group header
  function groupTemplate(data: any): JSX.Element {
    return <strong>{data.City}</strong>;
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={employeeData}
      query={query}
      fields={fields}
      groupTemplate={groupTemplate}
      sortOrder="Ascending"
      placeholder="Find an employee"
    />
  );
}

groupTemplate applies to both inline and floating (fixed) group headers. The same template is used for both.

---

Key Properties for Grouping

How-To: Autofill, Highlight Search, and Icon Support

Autofill

The autofill property makes the AutoComplete suggest the first matched item inline in the input as the user types. Pressing Arrow Down after typing confirms the inline suggestion. If no match is found, nothing is autofilled.

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const sportsData: { [key: string]: Object }[] = [
    { Id: 'Game1', Game: 'Badminton' },
    { Id: 'Game2', Game: 'Basketball' },
    { Id: 'Game3', Game: 'Cricket' },
    { Id: 'Game4', Game: 'Football' },
    { Id: 'Game5', Game: 'Golf' },
    { Id: 'Game6', Game: 'Hockey' },
    { Id: 'Game7', Game: 'Rugby' },
    { Id: 'Game8', Game: 'Snooker' },
  ];
  const fields: object = { value: 'Game' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={sportsData}
      fields={fields}
      autofill={true}
      placeholder="Find a game"
    />
  );
}

autofill works with filterType="StartsWith" for the most natural suggestion experience. When autofill is false (default), no inline suggestion is shown.

---

Highlight Search

Enable highlight={true} to visually highlight the typed characters within each suggestion in the popup list. The matched text is wrapped in an <span class="e-highlight"> element which can be styled:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const sportsData: { [key: string]: Object }[] = [
    { Id: 'Game1', Game: 'Badminton' },
    { Id: 'Game2', Game: 'Basketball' },
    { Id: 'Game3', Game: 'Cricket' },
    { Id: 'Game4', Game: 'Football' },
    { Id: 'Game5', Game: 'Golf' },
    { Id: 'Game6', Game: 'Hockey' },
    { Id: 'Game7', Game: 'Rugby' },
    { Id: 'Game8', Game: 'Snooker' },
  ];
  const fields: object = { value: 'Game' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={sportsData}
      fields={fields}
      highlight={true}
      placeholder="Find a game"
    />
  );
}

Customize the highlight appearance:

.e-highlight {
  font-weight: bold;
  color: #0056b3;
  background-color: #fff3cd;
}

---

Icon Support

Map an icon CSS class column to fields.iconCss to render an icon before each list item. The icon CSS class is applied to a <span> element prepended to the item text.

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const sortFormatData: { [key: string]: Object }[] = [
    { Class: 'asc-sort',  Type: 'Sort A to Z', Id: '1' },
    { Class: 'dsc-sort',  Type: 'Sort Z to A', Id: '2' },
    { Class: 'filter',    Type: 'Filter',       Id: '3' },
    { Class: 'clear',     Type: 'Clear',        Id: '4' },
  ];

  // iconCss maps to the 'Class' column which contains CSS class names
  const fields: object = { value: 'Type', iconCss: 'Class' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={sortFormatData}
      fields={fields}
      placeholder="Find a format"
    />
  );
}

Define the icon styles in your CSS:

.asc-sort::before  { content: '↑'; margin-right: 8px; }
.dsc-sort::before  { content: '↓'; margin-right: 8px; }
.filter::before    { content: '⊟'; margin-right: 8px; }
.clear::before     { content: '✕'; margin-right: 8px; }

You can use any icon library (Font Awesome, Material Icons, Syncfusion icons) by setting the appropriate class names in the iconCss data column.

Styling and Customization – Syncfusion React AutoComplete

Table of Contents

• CSS Class Targets
• Wrapper Element Appearance
• Dropdown Icon Color
• Focus Color
• Outline Theme Focus Color
• Disabled Text Color
• Float Label Focus Color
• Placeholder Text Color
• Text Selection Color
• Popup Item Background on Hover and Active
• Popup Item Appearance
• Mandatory Asterisk for Float Label
• cssClass Property
• Float Label Type
• Popup Resize

---

CSS Class Targets

The AutoComplete uses standard Syncfusion CSS class names that can be targeted for styling overrides.

---

Wrapper Element Appearance

.e-ddl.e-input-group.e-control-wrapper .e-input {
  font-size: 20px;
  font-family: emoji;
  color: #ab3243;
  background: #32a5ab;
}

---

Dropdown Icon Color

.e-ddl.e-input-group .e-input-group-icon,
.e-ddl.e-input-group.e-control-wrapper .e-input-group-icon:hover {
  color: #bb233d;
  font-size: 13px;
}

---

Focus Color

.e-ddl.e-input-group.e-control-wrapper.e-input-focus::before,
.e-ddl.e-input-group.e-control-wrapper.e-input-focus::after {
  background: #c000ff;
}

---

Outline Theme Focus Color

.e-outline.e-input-group.e-input-focus:hover:not(.e-success):not(.e-warning):not(.e-error):not(.e-disabled):not(.e-float-icon-left),
.e-outline.e-input-group.e-input-focus.e-control-wrapper:hover:not(.e-success):not(.e-warning):not(.e-error):not(.e-disabled):not(.e-float-icon-left),
.e-outline.e-input-group.e-input-focus:not(.e-success):not(.e-warning):not(.e-error):not(.e-disabled),
.e-outline.e-input-group.e-control-wrapper.e-input-focus:not(.e-success):not(.e-warning):not(.e-error):not(.e-disabled) {
  border-color: #b1bd15;
  box-shadow: inset 1px 1px #b1bd15, inset -1px 0 #b1bd15, inset 0 -1px #b1bd15;
}

---

Disabled Text Color

.e-input-group.e-control-wrapper .e-input[disabled] {
  -webkit-text-fill-color: #0d9133;
}

---

Float Label Focus Color

.e-float-input.e-input-group:not(.e-float-icon-left) .e-float-line::before,
.e-float-input.e-control-wrapper.e-input-group:not(.e-float-icon-left) .e-float-line::before,
.e-float-input.e-input-group:not(.e-float-icon-left) .e-float-line::after,
.e-float-input.e-control-wrapper.e-input-group:not(.e-float-icon-left) .e-float-line::after {
  background-color: #2319b8;
}

.e-ddl.e-input-group.e-control-wrapper.e-float-input.e-input-focus .e-float-text.e-label-top,
.e-float-input.e-control-wrapper:not(.e-error).e-input-focus input ~ label.e-float-text {
  color: #2319b8;
}

---

Placeholder Text Color

.e-ddl.e-input-group input.e-input::placeholder {
  color: red;
}

---

Text Selection Color

.e-ddl.e-input-group input.e-input::selection {
  color: red;
  background: yellow;
}

---

Popup Item Background on Hover and Active

.e-dropdownbase .e-list-item.e-item-focus,
.e-dropdownbase .e-list-item.e-active,
.e-dropdownbase .e-list-item.e-active.e-hover,
.e-dropdownbase .e-list-item.e-hover {
  background-color: #1f9c99;
  color: #2319b8;
}

---

Popup Item Appearance

.e-dropdownbase .e-list-item,
.e-dropdownbase .e-list-item.e-item-focus {
  background-color: #29c2b8;
  color: #207cd9;
  font-family: emoji;
  min-height: 29px;
}

---

Mandatory Asterisk for Float Label

Add a mandatory asterisk (*) to the float label:

.e-input-group.e-control-wrapper.e-float-input .e-float-text::after {
  content: ' *';
  color: red;
}

---

cssClass Property

Inject a custom CSS class onto the root element to scope styles:

<AutoCompleteComponent
  id="atcelement"
  dataSource={sportsData}
  cssClass="custom-autocomplete"
  placeholder="Find a game"
/>

.custom-autocomplete .e-input {
  border-radius: 8px;
}

---

Float Label Type

Control float label behavior with floatLabelType:

<AutoCompleteComponent
  id="atcelement"
  dataSource={sportsData}
  floatLabelType="Auto"   // 'Never' | 'Always' | 'Auto'
  placeholder="Find a game"
/>

---

Popup Resize

Allow users to dynamically resize the suggestion popup by dragging the resize handle in the bottom-right corner:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const statusData: { [key: string]: Object }[] = [
    { Status: 'Open',    State: false },
    { Status: 'On Hold', State: true  },
    { Status: 'Closed',  State: true  },
    { Status: 'Solved',  State: false },
  ];
  const fields: object = { value: 'Status' };

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={statusData}
      fields={fields}
      allowResize={true}
      placeholder="Select a status"
    />
  );
}

Resized dimensions are retained across sessions. Three resize-related events fire: resizeStart, resizing (continuous), and resizeStop.

Templates – Syncfusion React AutoComplete

Table of Contents

• Item Template
• Group Template
• Header Template
• Footer Template
• No Records Template
• Action Failure Template

---

Item Template

Customize the rendering of each suggestion list item using itemTemplate. Receives the data item as a parameter:

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const employeeData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });
  const query: Query = new Query()
    .from('Employees')
    .select(['FirstName', 'City', 'EmployeeID'])
    .take(6);
  const fields: object = { value: 'FirstName' };

  // Two-column layout: name + city
  function itemTemplate(data: any): JSX.Element {
    return (
      <span>
        <span className="name">{data.FirstName}</span>
        <span className="city">{data.City}</span>
      </span>
    );
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={employeeData}
      query={query}
      fields={fields}
      itemTemplate={itemTemplate}
      sortOrder="Ascending"
      placeholder="Find an employee"
    />
  );
}

---

Group Template

Customize the group header title rendered above grouped items using groupTemplate. Applies to both inline and floating headers:

import { DataManager, ODataV4Adaptor, Predicate, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const employeeData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });

  const groupPredicate = new Predicate('City', 'equal', 'london')
    .or('City', 'equal', 'seattle');

  const query: Query = new Query()
    .from('Employees')
    .select(['FirstName', 'City', 'EmployeeID'])
    .take(6)
    .where(groupPredicate);

  const fields: object = { value: 'FirstName', groupBy: 'City' };

  function groupTemplate(data: any): JSX.Element {
    return <strong>{data.City}</strong>;
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={employeeData}
      query={query}
      fields={fields}
      groupTemplate={groupTemplate}
      sortOrder="Ascending"
      placeholder="Find an employee"
    />
  );
}

---

Header Template

Place a static custom element at the top of the popup list using headerTemplate. Useful for column labels:

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const employeeData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });
  const query: Query = new Query()
    .from('Employees')
    .select(['FirstName', 'City', 'EmployeeID'])
    .take(6);
  const fields: object = { value: 'FirstName' };

  function headerTemplate(): JSX.Element {
    return (
      <span className="head">
        <span className="name">Name</span>
        <span className="city">City</span>
      </span>
    );
  }

  function itemTemplate(data: any): JSX.Element {
    return (
      <span className="item">
        <span className="name">{data.FirstName}</span>
        <span className="city">{data.City}</span>
      </span>
    );
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={employeeData}
      query={query}
      fields={fields}
      headerTemplate={headerTemplate}
      itemTemplate={itemTemplate}
      sortOrder="Ascending"
      placeholder="Find an employee"
    />
  );
}

---

Footer Template

Place a static custom element at the bottom of the popup list using footerTemplate. Useful for showing item counts:

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

export default function App() {
  const sportsData: string[] = [
    'Badminton', 'Basketball', 'Cricket', 'Football',
    'Golf', 'Gymnastics', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
  ];
  let atcObject: any;

  function onOpen(): void {
    const count = atcObject.getItems().length;
    const ele = document.getElementsByClassName('foot')[0] as HTMLElement;
    if (ele) ele.innerHTML = `Total list items: ${count}`;
  }

  function footerTemplate(): JSX.Element {
    return <span className="foot" />;
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      ref={(ac) => { atcObject = ac; }}
      dataSource={sportsData}
      footerTemplate={footerTemplate}
      open={onOpen}
      placeholder="Find a game"
    />
  );
}

---

No Records Template

Show a custom message when no matching items are found using noRecordsTemplate:

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const data: { [key: string]: Object }[] = [];

  function noRecordsTemplate(): JSX.Element {
    return <span className="norecord">No data available</span>;
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={data}
      noRecordsTemplate={noRecordsTemplate}
      placeholder="Find an item"
    />
  );
}

---

Action Failure Template

Show a custom message when a remote data fetch request fails using actionFailureTemplate:

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';
import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  // Intentionally broken URL to demonstrate failure template
  const customerData: DataManager = new DataManager({
    adaptor: new ODataV4Adaptor,
    crossDomain: true,
    url: 'url'
  });
  const query: Query = new Query()
    .from('Customers')
    .select(['ContactName', 'CustomerID'])
    .take(6);
  const fields: object = { value: 'ContactName' };

  function actionFailureTemplate(): JSX.Element {
    return <span className="action-failure">Data fetch failed</span>;
  }

  return (
    <AutoCompleteComponent
      id="atcelement"
      dataSource={customerData}
      query={query}
      fields={fields}
      actionFailureTemplate={actionFailureTemplate}
      placeholder="Find a customer"
    />
  );
}

---

Template Property Summary

Value Binding – Syncfusion React AutoComplete

Value binding associates a data value with the component. The AutoComplete supports binding both primitive types and full object values.

---

Primitive Data Types

Bind a string, number, boolean, or null value using the value property. The component will pre-select the matching item:

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

export default class App extends React.Component<{}, {}> {
  private records: string[] = [];
  private value: string = 'Item 1';

  constructor(props: {}) {
    super(props);
    this.records = Array.from({ length: 10 }, (_, i) => `Item ${i + 1}`);
  }

  public render() {
    return (
      <AutoCompleteComponent
        id="datas"
        dataSource={this.records}
        value={this.value}
        popupHeight="200px"
        placeholder="e.g. Item 1"
      />
    );
  }
}

Supported primitive types:

• string
• number
• boolean
• null (clears selection)

---

Object Data Types (allowObjectBinding)

When allowObjectBinding={true}, the value property holds a full object instead of a primitive. The object type matches the selected item in the data source.

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

export default class App extends React.Component<{}, {}> {
  private fields: object = { value: 'text' };
  private records: { [key: string]: Object }[] = [];

  // Pre-select "Item 1" by providing the full object
  private value: { [key: string]: Object } = { id: 'id1', text: 'Item 1' };

  constructor(props: {}) {
    super(props);
    this.records = Array.from({ length: 150 }, (_, i) => ({
      id: `id${i + 1}`,
      text: `Item ${i + 1}`,
    }));
  }

  public render() {
    return (
      <AutoCompleteComponent
        id="datas"
        dataSource={this.records}
        fields={this.fields}
        value={this.value as any}
        allowObjectBinding={true}
        popupHeight="200px"
        placeholder="e.g. Item 1"
      />
    );
  }
}

When allowObjectBinding is enabled, the change event's value argument will be the full matching object, not just a scalar value.

---

Key Properties

Virtualization – Syncfusion React AutoComplete

Table of Contents

• Overview
• Local Data Virtualization
• Remote Data Virtualization
• Customizing Item Count
• Grouping with Virtualization

---

Overview

Virtual scrolling renders only the visible DOM elements from a large dataset, recycling them as the user scrolls. This dramatically improves performance when working with hundreds or thousands of items.

Enable with:

• enableVirtualization={true} on the component
• <Inject services={[VirtualScroll]} /> inside the component

The actionBegin event fires before data is fetched; actionComplete fires after successful retrieval — both also fire during virtual scroll data requests.

When enableVirtualization is enabled, any skip/take set directly in the Query at the component's initial state will be ignored, as the virtual scroll manages pagination internally based on popup height and item height.

---

Local Data Virtualization

import { AutoCompleteComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default class App extends React.Component<{}, {}> {
  private fields: object = { value: 'text' };
  private records: { [key: string]: Object }[] = [];

  constructor(props: {}) {
    super(props);
    this.records = Array.from({ length: 150 }, (_, i) => ({
      id: `id${i + 1}`,
      text: `Item ${i + 1}`,
    }));
  }

  public render() {
    return (
      <AutoCompleteComponent
        id="datas"
        dataSource={this.records}
        fields={this.fields}
        enableVirtualization={true}
        popupHeight="200px"
        placeholder="e.g. Item 1"
      >
        <Inject services={[VirtualScroll]} />
      </AutoCompleteComponent>
    );
  }
}

---

Remote Data Virtualization

For remote data, the AutoComplete triggers additional fetch requests as the user scrolls, firing actionBegin and actionComplete each time:

import { AutoCompleteComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';
import { DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';
import * as React from 'react';

export default class App extends React.Component<{}, {}> {
  private customerField: object = { value: 'OrderID' };
  private customerData: DataManager = new DataManager({
    url: 'url',
    adaptor: new WebApiAdaptor,
    crossDomain: true
  });

  public render() {
    return (
      <AutoCompleteComponent
        id="datas"
        dataSource={this.customerData}
        fields={this.customerField}
        enableVirtualization={true}
        popupHeight="200px"
        placeholder="OrderID"
      >
        <Inject services={[VirtualScroll]} />
      </AutoCompleteComponent>
    );
  }
}

---

Customizing Item Count

When enableVirtualization is enabled, pass a Query with take() to control how many items are loaded per page. The internal calculation ensures at least enough items to fill the popup:

import { AutoCompleteComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';
import { Query } from '@syncfusion/ej2-data';
import * as React from 'react';

export default class App extends React.Component<{}, {}> {
  private fields: object = { value: 'text' };
  private records: { [key: string]: Object }[] = [];
  private query: Query = new Query().take(40);

  constructor(props: {}) {
    super(props);
    this.records = Array.from({ length: 150 }, (_, i) => ({
      id: `id${i + 1}`,
      text: `Item ${i + 1}`,
    }));
  }

  public render() {
    return (
      <AutoCompleteComponent
        id="datas"
        dataSource={this.records}
        fields={this.fields}
        query={this.query}
        enableVirtualization={true}
        popupHeight="200px"
        placeholder="e.g. Item 1"
      >
        <Inject services={[VirtualScroll]} />
      </AutoCompleteComponent>
    );
  }
}

If the provided take value is less than the minimum items needed to fill the popup, the user-provided value is ignored.

---

Grouping with Virtualization

Grouping works with virtualization. For remote data with grouping, an initial request fetches all data for grouping purposes, after which virtual scrolling is applied as with local data:

import { AutoCompleteComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default class App extends React.Component<{}, {}> {
  private fields: object = { groupBy: 'group', value: 'text' };
  private records: { [key: string]: Object }[] = [];

  constructor(props: {}) {
    super(props);
    const groups = ['Group A', 'Group B', 'Group C', 'Group D'];
    this.records = Array.from({ length: 150 }, (_, i) => ({
      id: `id${i + 1}`,
      text: `Item ${i + 1}`,
      group: groups[Math.floor(Math.random() * groups.length)],
    }));
  }

  public render() {
    return (
      <AutoCompleteComponent
        id="datas"
        dataSource={this.records}
        fields={this.fields}
        enableVirtualization={true}
        popupHeight="200px"
        placeholder="e.g. Item 1"
      >
        <Inject services={[VirtualScroll]} />
      </AutoCompleteComponent>
    );
  }
}

Advanced Features

Table of Contents

• Virtual Scrolling
• Internationalization (i18n)
• RTL Support
• Accessibility (WCAG)
• Disabled Items
• Keyboard Navigation

---

Virtual Scrolling

Enable Virtual Scrolling for Large Datasets

Virtual scrolling renders only visible items, dramatically improving performance with 10,000+ items.

Important: enableVirtualization requires injecting the VirtualScroll module via <Inject services={[VirtualScroll]} /> inside the component.

import { ComboBoxComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  // 50,000 items
  const largeDataset = Array.from({ length: 50000 }, (_, i) => ({
    id: i + 1,
    name: `Item ${i + 1}`
  }));

  return (
    <ComboBoxComponent 
      id="large-combo"
      dataSource={largeDataset}
      fields={{ text: 'name', value: 'id' }}
      enableVirtualization={true}      // ← Enable virtual scrolling
      allowFiltering={true}
      popupHeight="300px"
      placeholder="Searching 50,000 items efficiently..."
    >
      <Inject services={[VirtualScroll]} />
    </ComboBoxComponent>
  );
}

Benefits:

• ✅ Handles 50,000+ items without lag
• ✅ Smooth scrolling with filtering
• ✅ Reduced memory usage
• ✅ Faster initial render

When to use:

• >5,000 items
• Large remote datasets
• Performance-critical applications

Performance Comparison

---

Internationalization (i18n)

Change Language/Locale

import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns';
import { setDefaultCulture } from '@syncfusion/ej2-base';

// Set default culture before rendering
setDefaultCulture('es-ES');  // Spanish - Spain

export default function App() {
  return (
    <ComboBoxComponent 
      id="combo"
      dataSource={items}
      placeholder="Seleccionar..."    // Spanish placeholder
    />
  );
}

Supported locales:

• en-US - English (USA)
• es-ES - Spanish
• fr-FR - French
• de-DE - German
• ar-AE - Arabic
• ja-JP - Japanese
• zh-CN - Chinese (Simplified)
• And 20+ more...

Custom Localization

Create custom locale messages:

import { L10n } from '@syncfusion/ej2-base';

// Define custom translations
L10n.load({
  'es': {
    'combobox': {
      'noRecordsTemplate': 'Sin resultados encontrados',
      'actionFailureTemplate': 'Error al cargar datos'
    }
  },
  'fr': {
    'combobox': {
      'noRecordsTemplate': 'Aucun résultat trouvé',
      'actionFailureTemplate': 'Erreur de chargement des données'
    }
  }
});

<ComboBoxComponent 
  dataSource={items}
  locale="es"    // Use Spanish
/>

---

RTL Support

Enable Right-to-Left Layout

For Arabic, Hebrew, and other RTL languages:

import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns';
import { enableRtl } from '@syncfusion/ej2-base';

// Enable RTL globally
enableRtl(true);

export default function App() {
  const arabicItems = ['عنصر 1', 'عنصر 2', 'عنصر 3'];

  return (
    <ComboBoxComponent 
      id="arabic-combo"
      dataSource={arabicItems}
      placeholder="اختر..."    // Arabic placeholder
    />
  );
}

RTL-Specific Styling

/* RTL Layout */
.e-combobox[dir="rtl"] .e-input {
  text-align: right;
  direction: rtl;
}

.e-combobox[dir="rtl"] .e-clear-icon {
  left: 10px;   /* Swap left/right */
  right: auto;
}

.e-combobox[dir="rtl"] .e-dropdown-icon {
  right: 10px;
  left: auto;
}

---

Accessibility (WCAG)

WCAG 2.1 Compliance

ComboBox is built with accessibility in mind:

<ComboBoxComponent 
  id="accessible-combo"
  dataSource={items}
  fields={{ text: 'name', value: 'id' }}
  placeholder="Choose an option"
  aria-label="Select an item from the list"
  aria-describedby="combo-help"
/>

<small id="combo-help">Use arrow keys to navigate, Enter to select</small>

Keyboard Navigation

Screen Reader Support

ComboBox announces changes to screen readers:

export default function App() {
  return (
    <div>
      <label htmlFor="items-combo" className="sr-only">
        Select an item
      </label>
      <ComboBoxComponent 
        id="items-combo"
        dataSource={items}
        role="combobox"
        aria-expanded={isOpen}
        aria-owns="items-list"
      />
    </div>
  );
}

---

Disabled Items

Disable Specific Items

Some items should not be selectable:

export default function App() {
  const items = [
    { id: 1, name: 'Available', disabled: false },
    { id: 2, name: 'Unavailable', disabled: true },
    { id: 3, name: 'Available', disabled: false }
  ];

  const itemTemplate = (props) => {
    return (
      <div className={props.disabled ? 'item-disabled' : 'item'}>
        {props.name}
      </div>
    );
  };

  const filtering = (e) => {
    // Exclude disabled items from search results
    const searchText = e.text.toLowerCase();
    const filtered = items.filter(item =>
      !item.disabled && item.name.toLowerCase().includes(searchText)
    );
    e.updateData(filtered);
  };

  return (
    <ComboBoxComponent 
      dataSource={items}
      fields={{ text: 'name', value: 'id' }}
      allowFiltering={true}
      itemTemplate={itemTemplate}
      filtering={filtering}
    />
  );
}

CSS:

.item-disabled {
  color: #ccc;
  opacity: 0.6;
  pointer-events: none;
}

Disable Entire Component

Prevent interaction:

<ComboBoxComponent 
  dataSource={items}
  enabled={false}              // Disabled state
  placeholder="This is disabled"
/>

---

Keyboard Navigation

Responding to Selection via Keyboard

Use the select and change events to respond when a user picks an item through keyboard navigation:

export default function App() {
  const handleSelect = (e) => {
    // Fires when item is highlighted via keyboard and confirmed
    console.log('Item selected:', e.itemData);
  };

  const handleChange = (e) => {
    // Fires when value changes (keyboard or mouse)
    console.log('Value changed to:', e.value);
  };

  return (
    <ComboBoxComponent 
      dataSource={items}
      select={handleSelect}
      change={handleChange}
    />
  );
}

---

Common Advanced Patterns

Pattern 1: Conditional Disabling Based on Selection

export default function App() {
  const [selected, setSelected] = useState('');

  const items = [
    { id: 1, name: 'Option A' },
    { id: 2, name: 'Option B' }
  ];

  const handleChange = (e) => {
    setSelected(e.value);
  };

  return (
    <div>
      <ComboBoxComponent 
        dataSource={items}
        change={handleChange}
        placeholder="First selection"
      />
      
      <button disabled={!selected}>
        Submit {selected && `(${selected})`}
      </button>
    </div>
  );
}

Pattern 2: Large Dataset with Filtering & Virtual Scrolling

import { ComboBoxComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const largeDataset = Array.from({ length: 100000 }, (_, i) => ({
    id: i + 1,
    name: `Item ${i + 1}`,
    category: `Category ${(i % 10) + 1}`
  }));

  return (
    <ComboBoxComponent 
      id="mega-combo"
      dataSource={largeDataset}
      fields={{ text: 'name', value: 'id', groupBy: 'category' }}
      enableVirtualization={true}      // Critical for performance
      allowFiltering={true}
      filterType="Contains"
      popupHeight="400px"
      placeholder="Search 100,000 items..."
    >
      <Inject services={[VirtualScroll]} />
    </ComboBoxComponent>
  );
}

Pattern 3: Accessibility-First Implementation

export default function App() {
  const [selectedValue, setSelectedValue] = useState('');

  return (
    <div>
      <label htmlFor="accessible-combo">
        Select a priority level
        <abbr title="required">*</abbr>
      </label>
      
      <ComboBoxComponent 
        id="accessible-combo"
        dataSource={['Low', 'Medium', 'High']}
        value={selectedValue}
        change={(e) => setSelectedValue(e.value)}
        placeholder="Choose priority..."
        aria-required={true}
        aria-label="Select priority level for task"
        aria-describedby="combo-help"
      />
      
      <small id="combo-help" className="help-text">
        Use arrow keys to navigate options, press Enter to select
      </small>
    </div>
  );
}

---

Advanced Features Checklist

• [ ] Virtual scrolling enabled for large datasets (>5000 items) — enableVirtualization={true} with <Inject services={[VirtualScroll]} />
• [ ] Locale/culture set appropriately for audience
• [ ] RTL layout tested in browser
• [ ] Keyboard navigation verified (arrow keys, Enter, Escape)
• [ ] Screen reader tested with NVDA or JAWS
• [ ] Color contrast meets WCAG AA (4.5:1 for text)
• [ ] Focus indicators visible and clear
• [ ] Disabled state handled properly
• [ ] Performance tested with actual data volume

---

Next Steps

• Styling the component? → See styling-and-theming.md
• Having performance issues? → Check virtual scrolling section above
• Troubleshooting? → Visit troubleshooting.md
• Need localization details? → See Syncfusion i18n docs

Getting Started with DropDownList

This file covers installation, project setup, and the minimal working DropDownList implementation.

Installation

Install the Syncfusion dropdowns package:

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

CSS Imports

Add the following CSS imports in src/App.css. The tailwind3 theme is the current default:

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

Then import App.css in src/App.tsx:

import './App.css';

Important: Always use tailwind3 (not material or bootstrap) for current Syncfusion projects. Using an outdated theme name will result in missing styles.

Basic DropDownList

Functional Component (recommended)

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
import './App.css';

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

  return (
    <DropDownListComponent
      id="ddlelement"
      dataSource={sportsData}
      placeholder="Select a game"
    />
  );
}

Class Component

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';
import './App.css';

export default class App extends React.Component<{}, {}> {
  private sportsData: string[] = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'];

  public render() {
    return (
      <DropDownListComponent id="ddlelement" dataSource={this.sportsData} placeholder="Select a game" />
    );
  }
}

Binding a Data Source

Pass any array directly to dataSource. For JSON objects, also set the fields prop to map display text and value:

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

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

Configuring Popup Height and Width

By default the popup width matches the input element and the height is 300px. Override with popupHeight and popupWidth:

<DropDownListComponent
  id="ddlelement"
  dataSource={sportsData}
  popupHeight="200px"
  popupWidth="250px"
  placeholder="Select a game"
/>

Running the Application

npm run dev

Project Setup (Vite)

Create a new React + TypeScript project with Vite:

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install @syncfusion/ej2-react-dropdowns --save
npm run dev

See Also

• Data Binding — local arrays, JSON objects, remote data
• Filtering — search-as-you-type filtering
• Grouping & Templates — grouped items, custom templates