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](references/autocomplete-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](references/autocomplete-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](references/autocomplete-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](references/autocomplete-grouping.md) - Grouping items using `fields.groupBy` - Fixed and inline group headers - Custom group header with `groupTemplate` #### Templates 📄 **Read:** [references/templates.md](references/autocomplete-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](references/autocomplete-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](references/autocomplete-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](references/autocomplete-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](references/autocomplete-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](references/autocomplete-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](references/autocomplete-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](references/autocomplete-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 > ``` ```tsx 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 ```tsx 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. ```tsx 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 ```tsx <AutoCompleteComponent dataSource={sportsData} filterType="StartsWith" minLength={2} suggestionCount={5} debounceDelay={300} ignoreCase={true} placeholder="Type to search" /> ``` #### Accessing methods via ref ```tsx 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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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](references/combobox-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) ```tsx import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns'; import '@syncfusion/ej2-base/styles/tailwind3.css'; import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css'; export default function App() { const sportsList = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis']; return ( <ComboBoxComponent id="combobox" dataSource={sportsList} placeholder="Select a sport" allowCustom={true} /> ); } ``` #### With Data Binding (JSON Objects) ```tsx export default function App() { const sportsData = [ { Id: 'game1', Game: 'Badminton', Players: 2 }, { Id: 'game2', Game: 'Football', Players: 11 }, { Id: 'game3', Game: 'Cricket', Players: 11 } ]; const fields = { text: 'Game', value: 'Id' }; return ( <ComboBoxComponent id="combobox" dataSource={sportsData} fields={fields} placeholder="Select a game" change={(e) => console.log('Selected:', e.value)} /> ); } ``` --- ### Common Patterns #### Pattern 1: Filtered Search for User Selection **Problem:** User needs to find items in a list of 500+ entries.