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.

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 => acRef.current?.showPopup()}>Open</button>
      <button => 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.

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.

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.

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.

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: 'Nam

…(truncated)