syncfusion-blazor-dropdowns

# Implementing Syncfusion Blazor Dropdowns ## AutoComplete The AutoComplete component provides intelligent search suggestions as users type, supporting local and remote data sources with advanced filtering, customization, and accessibility features. ### Component Overview The **SfAutoComplete** component enables: - **Data Binding:** Local primitives, objects, or remote data sources - **Filtering:** Real-time search with debounce, filter types (StartsWith, Contains, EndsWith) - **Organization:** Grouping, sorting, multicolumn display - **Customization:** Item/group/header/footer templates, styling, placeholders - **Performance:** Virtualization for large datasets - **Accessibility:** WCAG compliance, keyboard navigation, ARIA support - **Interactions:** Events, disabled items, custom values, RTL support ### Documentation Navigation Guide Choose the reference that matches your current task: #### Getting Started 📄 **Read:** [references/getting-started.md](references/autocomplete-getting-started.md) - Installation of NuGet packages - Project setup (Visual Studio, VS Code, .NET CLI) - Basic autocomplete implementation - CSS imports and theme setup - Initial configuration #### Data Binding & Sources 📄 **Read:** [references/data-binding.md](references/autocomplete-data-binding.md) - Binding local data (primitives, objects, ObservableCollection) - Complex data types (ExpandoObject, DynamicObject) - Remote data with DataManager - ODataAdaptor, Web API, and custom adaptors - DataBound event handling #### Filtering & Search 📄 **Read:** [references/filtering-and-search.md](references/autocomplete-filtering-and-search.md) - Enabling and configuring filtering - Filter types (StartsWith, Contains, EndsWith) - Local vs. remote data filtering - DebounceDelay for performance - Minimum character length - Highlight search results #### Data Organization 📄 **Read:** [references/data-organization.md](references/autocomplete-data-organization.md) - Grouping data by categories - Sorting list items - Multicolumn display - Selection and selection modes - Value binding and custom values #### Templates & Styling 📄 **Read:** [references/templates-and-styling.md](references/autocomplete-templates-and-styling.md) - Item templates (custom list item layout) - Group templates (group header customization) - Header, footer, and no-records templates - CSS class styling - Placeholder and FloatLabel customization #### Advanced Features 📄 **Read:** [references/advanced-features.md](references/autocomplete-advanced-features.md) - Virtualization for large datasets - Popup settings and positioning - Disabled items handling - Custom values support - Localization and RTL support - Event handling (ActionBegin, ActionComplete, ValueChange, etc.) #### Accessibility & Best Practices 📄 **Read:** [references/accessibility-and-best-practices.md](references/autocomplete-accessibility-and-best-practices.md) - WCAG compliance and accessibility standards - ARIA attributes - Keyboard navigation support - Screen reader compatibility - Performance optimization tips - Common issues and troubleshooting ### Quick Start Example A minimal AutoComplete implementation with local data: ```blazor @using Syncfusion.Blazor.DropDowns <SfAutoComplete TValue="string" TItem="Country" DataSource="@Countries"> <AutoCompleteFieldSettings Value="CountryName"></AutoCompleteFieldSettings> </SfAutoComplete> @code { public class Country { public string CountryName { get; set; } } private List<Country> Countries = new() { new Country { CountryName = "Austria" }, new Country { CountryName = "Brazil" }, new Country { CountryName = "Canada" } }; } ``` ### Common Patterns #### Pattern 1: Filtering User Input Enable real-time filtering as users type: ```blazor <SfAutoComplete TValue="string" TItem="string" DataSource="@Options" AllowFiltering="true" FilterType="FilterType.Contains"> </SfAutoComplete> ``` #### Pattern 2: Remote Data with Debounce Reduce server requests with debounce delay: ```blazor <SfAutoComplete TValue="string" TItem="Product" AllowFiltering="true" DebounceDelay="300"> <SfDataManager Url="api/products" Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor"></SfDataManager> </SfAutoComplete> ``` #### Pattern 3: Custom Item Display with Templates Customize list item appearance: ```blazor <SfAutoComplete TValue="string" TItem="Product" DataSource="@Products"> <AutoCompleteTemplates TItem="Product"> <ItemTemplate> <div> <span>@((context as Product)?.ProductName)</span> <span style="float:right">@((context as Product)?.Price)</span> </div> </ItemTemplate> </AutoCompleteTemplates> </SfAutoComplete> ``` #### Pattern 4: Grouped & Sorted Display Organize data with grouping and sorting: ```blazor <SfAutoComplete TValue="string" TItem="Employee" DataSource="@Employees" SortOrder="SortOrder.Ascending"> <AutoCompleteFieldSettings GroupBy="Department" Value="EmployeeName"></AutoCompleteFieldSettings> </SfAutoComplete> ``` ### Key Props | Prop | Type | Purpose | |------|------|---------| | `DataSource` | `IEnumerable<TItem>` | Source data for suggestions | | `AllowFiltering` | `bool` | Enable/disable filtering | | `FilterType` | `FilterType` | Filter mode (StartsWith, Contains, EndsWith) | | `DebounceDelay` | `int` | Delay in ms before filter triggers | | `MinLength` | `int` | Min characters to trigger filtering | | `SortOrder` | `SortOrder` | Sort list items (Ascending, Descending) | | `EnableVirtualization` | `bool` | Virtualize large datasets | | `AllowCustom` | `bool` | Allow users to enter custom values | | `Placeholder` | `string` | Input placeholder text | | `FloatLabelType` | `FloatLabelType` | Floating label behavior | ### Common Use Cases 1. **Search-as-you-type:** Autocomplete on employee names, products, locations 2. **Filtered dropdowns:** Show matching items as users filter 3. **Remote APIs:** Fetch suggestions from backend services 4. **Multi-column display:** Show product details alongside names 5. **Grouped suggestions:** Organize by category or department 6. **Custom values:** Allow users to create new entries 7. **Large datasets:** Virtualize for performance with 1000+ items --- **Next Steps:** Start with [getting-started.md](references/autocomplete-getting-started.md) for setup, or jump to the reference that matches your task. --- ## ComboBox A comprehensive skill for implementing the ComboBox component. The ComboBox allows users to select a value from a dropdown list while also providing filtering, custom templates, cascading scenarios, data binding, and extensive customization options. ### When to Use This Skill Use this skill when you need to: - Install and set up the ComboBox component - Implement ComboBox with local or remote data sources - Configure data binding (primitive types, complex objects, collections) - Enable and configure filtering and search functionality - Handle value selection and change events - Create cascading ComboBox scenarios (dependent dropdowns) - Customize appearance with templates (items, header, footer) - Integrate ComboBox with form validation (EditForm, data annotations) - Configure popup settings (height, width, resize, positioning) - Apply grouping and sorting to ComboBox data - Handle events (ValueChange, OnValueSelect, Blur, etc.) - Implement accessibility and keyboard navigation - Customize styling and themes - Troubleshoot common ComboBox issues ### Quick Start Example ```razor @using Syncfusion.Blazor.DropDowns <SfComboBox TItem="Country" TValue="string" Placeholder="Select a country" DataSource="@CountryData" @bind-Value="@SelectedValue"> <ComboBoxFieldSettings Text="Name" Value="Code"></ComboBoxFieldSettings> </SfComboBox> @code { private string SelectedValue = "USA"; private List<Country> CountryData = new() { new Country { Name = "United States", Code = "USA" }, new Country { Name = "United Kingdom", Code = "UK" }, new Country { Name = "Canada", Code = "CA" } }; public class Country { public string Name { get; set; } public string Code { get; set; } } } ``` ### Key Props Reference | Property | Type | Purpose | |----------|------|---------| | `TValue` | Generic | Type of the selected value | | `TItem` | Generic | Type of data items in the list | | `DataSource` | IEnumerable | List of items to display | | `@bind-Value` | TValue | Two-way binding for selected value | | `@bind-Index` | int? | Two-way binding for selected index | | `Placeholder` | string | Hint text when no value selected | | `AllowFiltering` | bool | Enable/disable filtering | | `AllowCustom` | bool | Allow free-text entry | | `Readonly` | bool | Make component read-only | | `Disabled` | bool | Disable the component | ### Common Patterns #### Pattern 1: Basic Data Binding Bind ComboBox to local list with primitive or complex types. Use `ComboBoxFieldSettings` to map text/value fields. #### Pattern 2: Filtering & Search Enable `AllowFiltering` to let users filter data as they type. Control filter behavior with `FilterType` and `DebounceDelay`. #### Pattern 3: Cascading ComboBox Use `ValueChange` event in parent ComboBox to populate child ComboBox data dynamically based on parent selection. #### Pattern 4: Form Integration Wrap ComboBox in EditForm with data annotations for automatic validation. Use `ValidationMessage` to display errors. #### Pattern 5: Custom Templates Use `ItemTemplate`, `HeaderTemplate`, `FooterTemplate` to create custom UI for list items and popup sections. --- ### Documentation Navigation Guide Read the appropriate reference file based on your task: #### 📄 Getting Started **Read:** [references/getting-started.md](references/combobox-getting-started.md) - Installation and NuGet packages - Basic ComboBox implementation - Web App vs Server App setup - CSS imports and themes - First working example #### 📄 Data Binding **Read:** [references/data-binding.md](references/combobox-data-binding.md) - Local data binding (arrays, lists, collections) - Primitive type vs complex object binding - Index-based value binding - Remote data with DataManager - OData and Web API adaptors - Custom data adaptors - Dynamic object binding scenarios #### 📄 Filtering & Search **Read:** [references/filtering.md](references/combobox-filtering.md) - Enable filtering with `AllowFiltering` - Local vs remote data filtering - Filter types (contains, startsWith, endsWith) - Custom filtering logic - Debounce delay for performance - Case-sensitive filtering options #### 📄 Selection & Value Binding **Read:** [references/selection-and-value.md](references/combobox-selection-and-value.md) - Get and set selected value - Value vs Index binding - Preselected values on initialization - Programmatic value changes - Selection events (ValueChange, OnValueSelect) - Autofill functionality #### 📄 Cascading ComboBox **Read:** [references/cascading-combobox.md](references/combobox-cascading-combobox.md) - Create dependent/cascading ComboBox chains - Populate child ComboBox based on parent selection - Multi-level cascading (3+ levels) - Populate other form fields from selection - Real-world examples #### 📄 Templates & Customization **Read:** [references/templates-and-customization.md](references/combobox-templates-and-customization.md) - Item templates for custom list rendering - Group templates for grouped data - Header and footer templates - Value template customization - HTML content in templates - Template debugging tips #### 📄 Events & Validation **Read:** [references/events-and-validation.md](references/combobox-events-and-validation.md) - ComboBox events (Creating, Created, Blur, etc.) - ValueChange and OnValueSelect events - Form validation with EditForm - Data annotations and validation rules - Custom validation logic - Preventing operations with event cancellation #### 📄 Popup & Appearance **Read:** [references/popup-and-appearance.md](references/combobox-popup-and-appearance.md) - Popup height and width configuration - Popup positioning and z-index - Popup open/close events - Allow popup resize - Show popup on initial load - Placeholder and FloatLabel - CSS classes and styling #### 📄 Advanced Features **Read:** [references/advanced-features.md](references/combobox-advanced-features.md) - Grouping data by category - Sorting options and custom sort order - Virtualization for large datasets - Disabled items in the list - RTL (right-to-left) support - Accessibility (WCAG compliance) - Keyboard navigation #### 📄 Troubleshooting **Read:** [references/troubleshooting.md](references/combobox-troubleshooting.md) - Data not loading or empty list - Filtering not working as expected - Selection/binding issues - Event handlers not firing - Performance optimization tips - Common errors and solutions --- ### Common Use Cases **Use Case 1: Country/State/City Selection** - Create 3-level cascading ComboBox - User selects country → states populate → cities populate - See: Cascading ComboBox + Events & Validation **Use Case 2: Search/Filter List with Custom Display** - Enable filtering with custom templates - Show complex data (icons, descriptions, colors) - See: Filtering & Search + Templates & Customization **Use Case 3: Form with Multiple Dropdowns** - Integrate ComboBox into EditForm - Validate selections with data annotations - Cascade between dropdowns - See: Events & Validation + Cascading ComboBox **Use Case 4: Large Dataset Performance** - Bind to 1000+ items with virtualization - Enable remote filtering via API - Configure debounce delay - See: Advanced Features + Data Binding ### Key Features Summary ✅ **Local & Remote Data Binding** - Support for arrays, lists, observables, DataManager ✅ **Flexible Filtering** - Built-in filtering with customization options ✅ **Templates** - Item, group, header, footer templates for custom UI ✅ **Cascading** - Create dependent dropdown chains ✅ **Form Integration** - Native EditForm and validation support ✅ **Events** - Rich event system for user interactions ✅ **Accessibility** - WCAG compliance, keyboard navigation ✅ **Customization** - Theming, styling, CSS classes ✅ **Performance** - Virtualization support for large lists ✅ **RTL Support** - Right-to-left language support --- ### Related Components - **DropdownList** - Similar to ComboBox but without free-text entry - **AutoComplete** - Suggestive text input with dropdown - **MultiSelect** - Allow multiple selections from dropdown - **ListBox** - Scrollable list with selection support --- ## DropDown List A comprehensive skill for implementing the Syncfusion DropDown List component in Blazor applications. This component provides flexible item selection with support for data binding, filtering, templating, cascading, and extensive customization options. ### When to Use This Skill Use this skill when you need to: - Create a dropdown list component for item selection in Blazor - Bind dropdown data from local collections or remote APIs - Implement filtering and search functionality - Customize dropdown rendering with templates - Handle selection events and value binding