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

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

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

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

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

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

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

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:

@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:

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

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

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

<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

Search-as-you-type: Autocomplete on employee names, products, locations
Filtered dropdowns: Show matching items as users filter
Remote APIs: Fetch suggestions from backend services
Multi-column display: Show product details alongside names
Grouped suggestions: Organize by category or department
Custom values: Allow users to create new entries
Large datasets: Virtualize for performance with 1000+ items

Next Steps: Start with 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

@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

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

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

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

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

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

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

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

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

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

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
Create cascading dropdown relationships
Group and sort dropdown items
Implement form validation with dropdown selection
Apply styling and theming to dropdowns
Support accessibility and keyboard navigation
Enable RTL (Right-to-Left) support for localization
Manage large datasets with virtualization
Configure popup behavior and positioning
Handle disabled items and placeholders

Component Overview

Key Capabilities:

Multiple Selection: Select one or many items using various modes
Data Sources: Bind to collections, APIs, or custom data providers
Filtering: Built-in search with customizable filter options
Grouping & Sorting: Organize items hierarchically with sorting
Custom Templates: Design custom item, group, header, and footer templates
Keyboard Navigation: Full keyboard support and accessibility (WCAG 2.1)
Theming: Bootstrap, Material, Fluent, Tailwind themes with light/dark modes
Validation: Form validation support with custom validators
RTL & Localization: Right-to-left language support and multi-language
Virtualization: Handle large datasets efficiently

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started-dropdown-list.md

Installation and NuGet package setup
Basic component implementation
CSS theme imports
Minimal working example
Rendering the dropdown

Data Binding

📄 Read: references/data-binding.md

Binding local collections (primitives, complex types, observables)
Remote data binding with Web API and OData
Data source events (OnActionBegin, OnActionComplete)
Dynamic and enum data binding
Value tuple and expando object binding

Filtering and Searching

📄 Read: references/filtering-and-searching.md

Filter types and strategies
Case-sensitive filtering
Minimum filter length configuration
Debounce delay for performance optimization
Multi-column filtering
Custom filtering logic

Templates and Rendering

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

Item template customization
Header and footer templates
Value template for selection display
Conditional rendering in templates
Complex template patterns

Selection and Value Binding

📄 Read: references/selection-and-value-binding.md

Getting and setting selected values
Value binding with @bind-Value directive
Value changed events
Clearing and resetting selection
Working with complex object selections

Customization and Styling

📄 Read: references/customization-and-styling.md

Opening dropdown on focus
CSS class application
Theme application and switching
Component sizing and appearance
Styling open and closed states

Advanced Features

📄 Read: references/advanced-features.md

Cascading dropdowns for dependent selections
Item grouping and organization
Sorting and ordering options
Disabled items and states
Placeholder text and float label
Popup settings and positioning
Virtualization for large datasets

Form Validation

📄 Read: references/form-validation.md

EditForm integration
Data annotation validation
Validation error display
Custom validation rules
Form submission patterns

Localization and RTL

📄 Read: references/localization-and-rtl.md

RTL (Right-to-Left) support
Localization patterns
Culture-specific formatting
Multi-language support

Accessibility

📄 Read: references/accessibility.md

WCAG 2.1 compliance
WAI-ARIA attributes and roles
Keyboard navigation (Arrow keys, Enter, Escape)
Screen reader compatibility
Focus management
High contrast support

Quick Start

Basic Dropdown Implementation

@page "/dropdown-demo"

<h3>Simple Dropdown List</h3>

<SfDropDownList TValue="int" TItem="Country" DataSource="@Countries" Placeholder="Select a country">
    <DropDownListFieldSettings Text="@nameof(Country.CountryName)" Value="@nameof(Country.CountryId)" />
</SfDropDownList>

@code {
    public List<Country> Countries { get; set; }

    protected override void OnInitialized()
    {
        Countries = new List<Country>
        {
            new Country { CountryId = 1, CountryName = "United States" },
            new Country { CountryId = 2, CountryName = "Canada" },
            new Country { CountryId = 3, CountryName = "Mexico" }
        };
    }

    public class Country
    {
        public int CountryId { get; set; }
        public string CountryName { get; set; }
    }
}

With Value Binding and Selection Event

<SfDropDownList TValue="int" TItem="Country" @bind-Value="SelectedCountryId"
                DataSource="@Countries"
                Placeholder="Choose a country">
    <DropDownListFieldSettings Text="@nameof(Country.CountryName)" Value="@nameof(Country.CountryId)" />
    <DropDownListEvents TValue="int" TItem="Country" ValueChange="@OnValueChange"></DropDownListEvents>
</SfDropDownList>

<p>Selected: @SelectedCountryId</p>

@code {
    private int SelectedCountryId;
    
    protected override void OnInitialized()
    {
        Countries = new List<Country>
        {
            new Country { CountryId = 1, CountryName = "United States" },
            new Country { CountryId = 2, CountryName = "Canada" },
            new Country { CountryId = 3, CountryName = "Mexico" }
        };
    }

    public class Country
    {
        public int CountryId { get; set; }
        public string CountryName { get; set; }
    }

    private void OnValueChange(ChangeEventArgs<int, Country> args)
    {
        SelectedCountryId = args.Value;
        // Handle value change
    }
}

Common Patterns

Pattern 1: Dropdown with Filtering

Enable filter-as-you-type functionality to let users quickly find items in large lists:

<SfDropDownList TValue="string" TItem="string"
                DataSource="@Items"
                AllowFiltering="true"
                FilterType="Syncfusion.Blazor.DropDowns.FilterType.Contains"
                Placeholder="Type to filter">
</SfDropDownList>

Pattern 2: Cascading Dropdowns

Create dependent dropdowns where selection in one dropdown affects the options in another:

<SfDropDownList TValue="int" TItem="Country" @bind-Value="SelectedCountry"
                DataSource="@Countries"
                Placeholder="Select Country">
    <DropDownListFieldSettings Text="@nameof(Country.Name)" Value="@nameof(Country.Id)" />
    <DropDownListEvents TValue="int" TItem="Country" ValueChange="@OnCountryChange"></DropDownListEvents>
</SfDropDownList>

<SfDropDownList TValue="int" TItem="City"
                DataSource="@FilteredCities"
                Placeholder="Select City">
    <DropDownListFieldSettings Text="@nameof(City.Name)" Value="@nameof(City.Id)" />
</SfDropDownList>

@code {
    private int SelectedCountry;
    private List<City> FilteredCities;

    private void OnCountryChange(ChangeEventArgs<int, Country> args)
    {
        SelectedCountry = args.Value;
        FilteredCities = Cities.Where(c => c.CountryId == SelectedCountry).ToList();
    }
}

Pattern 3: Remote Data Binding

Connect to APIs for dynamic data loading:

<SfDropDownList TValue="int" TItem="DataItem"
                DataSource="@RemoteData"
                Placeholder="Select item">
    <DropDownListFieldSettings Text="@nameof(DataItem.CountryName)" Value="@nameof(DataItem.CountryId)" />
    <DropDownListEvents TValue="int" TItem="DataItem" OnActionComplete="@OnActionComplete"></DropDownListEvents>
</SfDropDownList>

@code {
    private List<DataItem> RemoteData;
    
    private async Task OnActionComplete(ActionCompleteEventArgs<DataItem> args)
    {
        var response = await HttpClient.GetAsync("api/items");
        RemoteData = await response.Content.ReadAsAsync<List<DataItem>>();
    }

    public class DataItem
    {
        public int CountryId { get; set; }
        public string CountryName { get; set; }
    }
}

Pattern 4: Custom Item Template

Use templates to display rich content in dropdown items:

<SfDropDownList TValue="int" TItem="Employee" DataSource="@Employees">
    <DropDownListFieldSettings Text="@nameof(Employee.EmployeeName)" Value="@nameof(Employee.Id)" />
    <DropDownListTemplates TValue="Employee">
        <ItemTemplate>
            <span>@context.EmployeeName - @context.Designation</span>
        </ItemTemplate>
    </DropDownListTemplates>
</SfDropDownList>

Pattern 5: Form Validation

Integrate with EditForm for validation:

<EditForm Model="@FormModel">
    <DataAnnotationsValidator />
    <ValidationSummary />
    
    <div class="form-group">
        <label>Select Department</label>
        <SfDropDownList TValue="int" TItem="Department" @bind-Value="FormModel.DepartmentId"
                        DataSource="@Departments"
                        Placeholder="Choose department">
            <DropDownListFieldSettings Text="@nameof(Department.Name)" Value="@nameof(Department.Id)" />
        </SfDropDownList>
    </div>
    
    <button type="submit">Submit</button>
</EditForm>

@code {
    private FormData FormModel = new();
    
    public class FormData
    {
        [Required(ErrorMessage = "Department is required")]
        public int DepartmentId { get; set; }
    }
}

Key Props and Events

Essential Properties

Property	Description
`DataSource`	`IEnumerable<T>` Collection of items to display
`Value` / `@bind-Value`	`TValue` Currently selected value
`Placeholder`	`string` Hint text when no selection
`AllowFiltering`	`bool` Enable search/filter functionality
`FilterType`	`FilterType` Filter strategy (StartsWith, Contains, EndsWith)
`Enabled`	`bool` Enable or disable the dropdown
`EnableRtl`	`bool` Right-to-Left text direction
`Width`	`string` Component width (px, %, etc.)

Field mapping: Use the <DropDownListFieldSettings Text="..." Value="..." /> child component tag to map data fields.

Essential Events (inside `<DropDownListEvents>`)

Event	Description
`ValueChange`	Triggered when selected value changes
`OnActionBegin`	Before remote data fetch begins
`OnActionComplete`	After remote data fetch completes
`OnActionFailure`	When remote data fetch fails
`OnOpen`	When dropdown opens
`OnClose`	When dropdown closes
`Focus`	When component receives focus
`Blur`	When component loses focus

Common Use Cases

User Selection in Forms - Select users from a list for assignment or notification
Category/Type Selection - Choose from predefined categories or types
Cascading Selections - Dependent dropdowns (Country → State → City)
Dynamic Data from APIs - Load options from backend services
Searchable Lists - Filter through large datasets efficiently
Multi-stage Workflows - Selection-based form navigation
Data Filtering - Apply filters based on dropdown selection
Templated Dropdowns - Display rich content (images, descriptions)
Localized Selections - Region/language-specific options
Accessibility-Compliant Forms - WCAG-compliant selection interface

Related Components

ComboBox - Editable dropdown with text input capability
AutoComplete - Text input with auto-suggestion dropdown
ListBox - Multi-item list with selection options
MultiSelect Dropdown - Select multiple items from a list
Mention - @mention autocomplete (like social media)

Next Steps

Choose your use case from "Common Use Cases" above
Navigate to the relevant reference guide in the "Documentation and Navigation Guide" section
Copy the pattern example and adapt it to your specific data and requirements
Consult the specific reference for advanced configurations and edge cases

For detailed implementation patterns, complete code examples, and troubleshooting guidance, read the appropriate reference file based on your specific needs.

MultiSelect Dropdown

The MultiSelect Dropdown component enables users to select multiple items from a list with support for filtering, grouping, sorting, keyboard navigation, accessibility, and extensive customization options. This skill guides you through installation, implementation, data binding, features, customization, and advanced scenarios.

When to Use This Skill

Use this skill when you need to:

Install and configure the MultiSelect Dropdown component in Blazor projects
Implement multiple item selection in forms and applications
Set up data binding with collections, APIs, or remote sources
Configure selection modes (Checkbox, Delimiter, Box)
Add filtering and grouping capabilities to dropdowns
Customize appearance, styling, and templates
Implement keyboard navigation and accessibility features
Handle selection events and programmatic selection
Support localization, RTL, and globalization
Optimize performance with virtualization
Integrate with forms and validation

Component Overview

Key Capabilities:

Multiple Selection: Select one or many items using various modes
Data Sources: Bind to collections, APIs, or custom data providers
Filtering: Built-in search with customizable filter options
Grouping & Sorting: Organize items hierarchically with sorting
Custom Templates: Design custom item, group, header, and footer templates
Keyboard Navigation: Full keyboard support and accessibility (WCAG 2.1)
Theming: Bootstrap, Material, Fluent, Tailwind themes with light/dark modes
Validation: Form validation support with custom validators
RTL & Localization: Right-to-left language support and multi-language
Virtualization: Handle large datasets efficiently

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Installation and NuGet package setup
Basic MultiSelect Dropdown implementation
Namespace imports and service registration
Theme application
Minimal working example
Common setup troubleshooting

Data Binding

📄 Read: references/data-binding.md

Binding to collections (List, ObservableCollection)
Remote data binding and API integration
Custom data adapters and sources
Value binding patterns
Handling null and empty data
Performance considerations

Features and Selection

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

Selection modes (Checkbox, Delimiter, Box)
Single vs. multiple item selection
Select/deselect all functionality
Programmatic selection and value updates
Custom values and free-form text input
Default selected values
Disabled items and item groups
Virtualization for large datasets

Filtering and Grouping

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

Enable and configure filtering
Filter placeholder and debounce delay
Custom filter implementation
Case-sensitive and multi-field filtering
Remote filtering from APIs
Data grouping with group headers
Sorting within groups
Filter performance optimization

Customization and Styling

📄 Read: references/customization-and-styling.md

CSS classes and theme customization
Placeholder and floating labels
Icon support (prefix/suffix icons)
Popup width and height customization
Chip display modes and styling
Popup positioning
RTL (Right-to-Left) support
Dark mode implementation
Custom CSS variables and overrides

Accessibility and Templates

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

ARIA attributes and screen reader support
Keyboard navigation shortcuts
Focus management and visual focus indicators
WCAG 2.1 compliance
ItemTemplate for custom item rendering
GroupTemplate for custom group headers
HeaderTemplate and FooterTemplate
Template binding and context
Accessibility in custom templates

Events and API Reference

📄 Read: references/events-and-api.md

Complete event reference (Change, Focus, Blur, Open, Close)
Event handling patterns in Blazor
Event arguments and return values
Component API methods (Open, Close, Focus, Refresh)
Property access and state updates
Reactive patterns for state management
Real-world event handling examples

Advanced Scenarios

📄 Read: references/advanced-scenarios.md

Form integration and validation
Localization and globalization setup
Custom value creation and suggestion
Performance optimization techniques
Multiple dropdown instances management
Server-side vs. client-side filtering
Real-world use cases and patterns
Edge cases and troubleshooting
Best practices and gotchas

Quick Start

Minimal Example

1. Install NuGet Package:

dotnet add package Syncfusion.Blazor.DropDowns

2. Add to _Imports.razor:

@using Syncfusion.Blazor
@using Syncfusion.Blazor.DropDowns

3. Register Service in Program.cs:

builder.Services.AddSyncfusionBlazor();

4. Add Theme in App.razor:

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

5. Use MultiSelect Dropdown:

@page "/multiselect-demo"
@using Syncfusion.Blazor.DropDowns

<SfMultiSelect DataSource="@Employees" 
               TValue="List<string>"
               TItem="EmployeeData"
               Placeholder="Select employees">
    <MultiSelectFieldSettings Text="Name" Value="ID"></MultiSelectFieldSettings>
</SfMultiSelect>

@code {
    private List<EmployeeData> Employees { get; set; } = new();

    protected override void OnInitialized()
    {
        Employees = new List<EmployeeData>
        {
            new() { ID = "1", Name = "Alice Johnson" },
            new() { ID = "2", Name = "Bob Smith" },
            new() { ID = "3", Name = "Carol White" }
        };
    }

    public class EmployeeData
    {
        public string ID { get; set; }
        public string Name { get; set; }
    }
}

Common Patterns

Pattern 1: Two-Way Binding with Selection Change

@page "/multiselect-binding"
@using Syncfusion.Blazor.DropDowns

<div>
    <p>Selected IDs: @string.Join(", ", SelectedValues)</p>
    <SfMultiSelect DataSource="@Items" 
                   @bind-Value="SelectedValues"
                   TValue="List<string>"
                   TItem="ItemData"
                   Placeholder="Select items">
        <MultiSelectFieldSettings Text="Name" Value="ID"></MultiSelectFieldSettings>
    </SfMultiSelect>
</div>

@code {
    private List<string> SelectedValues { get; set; } = new();
    private List<ItemData> Items { get; set; } = new();

    protected override void OnInitialized()
    {
        Items = new List<ItemData>
        {
            new() { ID = "1", Name = "Item 1" },
            new() { ID = "2", Name = "Item 2" },
            new() { ID = "3", Name = "Item 3" }
        };
    }

    public class ItemData
    {
        public string ID { get; set; }
        public string Name { get; set; }
    }
}

Pattern 2: Filtering with Remote Data

<SfMultiSelect DataSource="@RemoteData" 
               TValue="List<string>"
               TItem="RemoteItem"
               AllowFiltering="true"
               ShowCheckbox="true"
               Placeholder="Search and select">
    <MultiSelectFieldSettings Text="Text" Value="ID"></MultiSelectFieldSettings>
    <MultiSelectEvents TValue="List<string>" TItem="RemoteItem" 
                       Filtering="OnFiltering">
    </MultiSelectEvents>
</SfMultiSelect>

@code {
    private List<RemoteItem> RemoteData { get; set; } = new();

    private async Task OnFiltering(FilteringEventArgs args)
    {
        // Filter items based on search text
        args.PreventDefaultAction = true;
        var filtered = RemoteData
            .Where(x => x.Text.Contains(args.Text, StringComparison.OrdinalIgnoreCase))
            .ToList();
        
        // Update DataSource with filtered results
        // (Implementation depends on your component reference handling)
    }

    public class RemoteItem
    {
        public string ID { get; set; }
        public string Text { get; set; }
    }
}

Pattern 3: Custom Validation in Form

<EditForm Model="FormData" OnValidSubmit="HandleSubmit">
    <DataAnnotationsValidator />
    
    <div class="form-group">
        <label>Select at least 2 items:</label>
        <SfMultiSelect DataSource="@Items"
                       @bind-Value="FormData.SelectedItems"
                       TValue="List<string>"
                       TItem="ItemData"
                       Placeholder="Select items">
            <MultiSelectFieldSettings Text="Name" Value="ID"></MultiSelectFieldSettings>
        </SfMultiSelect>
        <ValidationMessage For="@(() => FormData.SelectedItems)" />
    </div>
    
    <button type="submit">Submit</button>
</EditForm>

@code {
    private FormModel FormData { get; set; } = new();
    private List<ItemData> Items { get; set; } = new();

    private async Task HandleSubmit()
    {
        // Handle form submission
    }

    public class FormModel
    {
        [Required(ErrorMessage = "Please select items")]
        [MinLength(2, ErrorMessage = "Select at least 2 items")]
        public List<string> SelectedItems { get; set; } = new();
    }

    public class ItemData
    {
        public string ID { get; set; }
        public string Name { get; set; }
    }
}

Key Props Reference

Property	Type	Description	When to Use
`DataSource`	`IEnumerable<T>`	Collection of items to display	Always required
`Value`	`List<T>`	Currently selected values	Binding selections
`Placeholder`	`string`	Placeholder text when empty	UX improvement
`AllowFiltering`	`bool`	Enable/disable search filtering	For searchable lists
`ShowCheckbox`	`bool`	Show checkboxes for selection	Explicit selection mode
`Mode`	`VisualMode`	Selection display mode (Box, Delimiter, Default)	Customize chip display
`Disabled`	`bool`	Enable/disable component	Conditional states
`AllowCustomValue`	`bool`	Allow user-entered custom values	Free-form input
`EnableVirtualization`	`bool`	Enable virtualization for large data	Performance optimization
`AllowGrouping`	`bool`	Enable item grouping	Organize items
`PopupHeight`	`string`	Height of dropdown popup	Customize appearance
`CssClass`	`string`	Custom CSS class	Custom styling

Common Use Cases

Case 1: Employee Selection in Team Assignment

User needs to select multiple employees for a team
Use checkbox mode for clear selection
Add filtering for easier search
Validate minimum selection requirement

Case 2: Category/Tag Selection for Content

User tags content with multiple categories
Use custom values for new tags
Show selected items as chips
Allow deselect with delete key

Case 3: Department/Location Multi-Filter

Filter data by multiple departments and locations
Remote data source from API
Grouping by department/location
Programmatic selection updates

Case 4: Subscription Preferences

User selects multiple notification types
Grouping by category (Email, SMS, Push)
All-select/deselect functionality
RTL support for international apps

Ready to implement MultiSelect Dropdown? Start with Getting Started for setup, then navigate to other references based on your specific needs.

Mention

The Mention component provides @mention functionality for tagging users, items, or entities within text content. It displays a suggestion list when users type a trigger character (default: @), enabling easy selection and insertion of tagged items.

When to Use This Skill

Use the Mention component when you need to:

Add @mention tagging in comments, chat, or social features
Tag users, products, or entities in text areas
Implement autocomplete suggestions with a trigger character
Create collaborative commenting systems
Build social media-style mention features
Enable context-aware item selection in text input

Component Overview

The Mention component is a dropdown that enables users to mention items from a configured data source by typing a trigger character (default: @). It displays a filtered suggestion list that users can select from, automatically inserting the mention into the target element.

Key Capabilities

Trigger-based suggestions: Displays suggestions when users type the mention character
Multiple data source types: Supports local primitives, complex objects, enums, and remote data
Advanced filtering: StartsWith, Contains, EndsWith filter types with minimum character limits
Templating: Customize item display, mention format, empty states, and loading indicators
Accessibility: Full WCAG 2.2 compliance with keyboard navigation and screen reader support
Remote data: OData v4, Web API adaptors with offline mode support

Documentation & Navigation Guide

Choose your topic below to get started:

📄 Getting Started

Read: references/getting-started.md

Installation and package setup (NuGet, themes)
Creating Blazor WASM and Server applications
Basic Mention component implementation
Target element configuration (div, textarea, input)
Initial data binding

📄 Working with Data

Read: references/working-with-data.md

Binding local data (primitives, complex objects, ExpandoObject)
Enum data binding
Remote data binding with DataManager
OData v4 and Web API adaptors
Offline mode for caching
Data fetch events (ActionBegin, ActionComplete, ActionFailure)

📄 Filtering & Search

Read: references/filtering-and-search.md

MinLength property for minimum search characters
FilterType options (StartsWith, Contains, EndsWith)
AllowSpaces for multi-word searching
SuggestionCount for result limiting

📄 Customization

Read: references/customization.md

ShowMentionChar to display mention character in selected text
SuffixText for adding space or newline after mention
Popup dimensions (PopupHeight, PopupWidth)
Custom mention trigger character
RequireLeadingSpace for space-prefixed triggers

📄 Templates & Display

Read: references/templates.md

ItemTemplate for custom suggestion list styling
DisplayTemplate for formatted mention display
NoRecordsTemplate for empty states
SpinnerTemplate for loading states
Template context access and data usage

📄 Accessibility

Read: references/accessibility.md

WCAG 2.2 compliance details
WAI-ARIA attributes (aria-selected, aria-activedescendent)
Keyboard navigation shortcuts
Screen reader support
Mobile and RTL language support

Quick Start Example

<SfMention TItem="PersonData" DataSource="@TeamMembers">
    <TargetComponent>
        <textarea id="mentionTarget" placeholder="Type @ to mention someone"></textarea>
    </TargetComponent>
    <ChildContent>
        <MentionFieldSettings Text="Name"></MentionFieldSettings>
    </ChildContent>
</SfMention>

<style>
    #mentionTarget {
        min-height: 100px;
        border: 1px solid #D7D7D7;
        border-radius: 4px;
        padding: 8px;
        font-size: 14px;
        width: 100%;
    }
</style>

@code {
    public class PersonData
    {
        public string Name { get; set; }
        public string Email { get; set; }
    }

    List<PersonData> TeamMembers = new List<PersonData>
    {
        new PersonData { Name = "Alice Johnson", Email = "alice@company.com" },
        new PersonData { Name = "Bob Smith", Email = "bob@company.com" },
        new PersonData { Name = "Carol White", Email = "carol@company.com" }
    };
}

Common Patterns

Pattern 1: Comment Section with User Mentions

<SfMention TItem="UserData" DataSource="@AllUsers" MentionChar="@">
    <TargetComponent>
        <div id="comments" contenteditable="true" placeholder="Type @ to mention..."></div>
    </TargetComponent>
    <ChildContent>
        <MentionFieldSettings Text="UserName"></MentionFieldSettings>
    </ChildContent>
</SfMention>

Pattern 2: Filtered Suggestions with Remote Data

<SfMention TItem="EmployeeData" MinLength="2" FilterType="FilterType.StartsWith">
    <TargetComponent>
        <input id="employeeInput" type="text" placeholder="Search employees..." />
    </TargetComponent>
    <ChildContent>
        <SfDataManager Url="https://api.example.com/employees" Adaptor="Adaptors.WebApiAdaptor"></SfDataManager>
        <MentionFieldSettings Text="Name"></MentionFieldSettings>
    </ChildContent>
</SfMention>

Pattern 3: Custom Display with Templates

<SfMention TItem="PersonData" DataSource="@TeamMembers">
    <TargetComponent>
        <div id="mentionDiv" contenteditable="true"></div>
    </TargetComponent>
    <ItemTemplate>
        <div class="mention-item">
            <span>@((context as PersonData).Name)</span>
            <small>@((context as PersonData).Email)</small>
        </div>
    </ItemTemplate>
    <DisplayTemplate>
        <span class="mentioned-user">@((context as PersonData).Name)</span>
    </DisplayTemplate>
    <ChildContent>
        <MentionFieldSettings Text="Name"></MentionFieldSettings>
    </ChildContent>
</SfMention>

Key Properties

Property	Type	Default	Purpose
`TItem`	Generic	-	Data source item type
`DataSource`	IEnumerable	-	Local data collection
`MentionChar`	string	`@`	Trigger character for suggestions
`Target`	string	-	CSS selector for target element
`MinLength`	int	0	Minimum characters to show suggestions
`FilterType`	FilterType	Contains	Search filter mode (StartsWith, Contains, EndsWith)
`AllowSpaces`	bool	false	Allow spaces in mention search
`ShowMentionChar`	bool	false	Display trigger character with mention
`SuffixText`	string	-	Text appended after mention (space, newline)
`RequireLeadingSpace`	bool	false	Require space before mention character
`PopupHeight`	string	300px	Suggestion list height
`PopupWidth`	string	auto	Suggestion list width
`SuggestionCount`	int	25	Maximum items in suggestion list

Common Use Cases

User Tagging in Comments

Create collaboration tools where users mention @username in comments
Combine with DisplayTemplate to show user avatars
Use remote data binding to fetch team members dynamically

Task Assignment Notifications

Mention team members when assigning tasks
Customize MentionChar to use # for tasks, @ for users
Use ActionComplete event to log mentions for notifications

Code or Entity References

Use Mention to reference code snippets (#snippet)
Mention entities or resources in documentation
Support enum data binding for predefined entities

Multi-target Mention

Implement mention support in multiple textareas on same page
Each Mention component can target a different element
Use Target property with unique CSS selectors

Next Steps

Start here: Read Getting Started to install and set up
Bind data: Learn Working with Data for local/remote sources
Enhance UX: Explore Filtering & Search and Templates
Ensure accessibility: Review Accessibility for inclusive design
Fine-tune: Use Customization for appearance and behavior adjustments

For additional help:

Official Documentation: https://blazor.syncfusion.com/documentation/mention/getting-started
API Reference: https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfMention-1.html
Community Support: https://www.syncfusion.com/forums/blazor

ListBox

A comprehensive skill for implementing and working with the SfListBox component in Blazor applications. The ListBox displays a scrollable list of items with support for single/multiple selection, checkboxes, filtering, drag-and-drop, icons, and custom templates.

When to Use This Skill

Use this skill when you need to:

Installation & Setup
- Install Syncfusion.Blazor.DropDowns NuGet package
- Register services and configure themes
- Set up Blazor WebAssembly, Server, or Web App projects
Data Binding
- Bind array of strings or objects to ListBox
- Map complex nested objects to list items
- Load data from remote sources (DataManager, APIs)
- Update data dynamically
Selection & Interaction
- Implement single or multiple selection modes
- Add checkboxes for item selection
- Enable "Select All" functionality
- Set maximum selection limits
- Retrieve selected items and values
- Handle selection change events
Features & Customization
- Enable filtering and search capabilities
- Implement drag-and-drop reordering
- Create dual-listbox patterns (source/target)
- Enable/disable specific items
- Add icons and custom templates
- Apply sorting and grouping
Styling & Appearance
- Apply themes (Bootstrap, Material, Fluent, Tailwind)
- Customize CSS and styling
- Create responsive layouts
- Implement dark mode
Accessibility
- Ensure WCAG 2.1 compliance
- Configure keyboard navigation
- Add ARIA labels and roles
- Support screen readers

Component Overview

The SfListBox component is a flexible dropdown alternative that displays items in a scrollable list format.

Key Characteristics:

TValue: Type parameter for selected values (e.g., string[], int[])
TItem: Type parameter for data source items
Multiple Selection: Default behavior; supports single mode
Checkbox Support: Optional checkboxes for item selection
Field Mapping: Maps data object properties to display and value
Templates: Supports custom item templates for rich formatting
Data Binding: Supports local arrays, objects, remote data
Events: Change, select, focus events for interaction handling

Quick Start Example

@using Syncfusion.Blazor.DropDowns

<SfListBox TValue="string[]" DataSource="@Items" TItem="string"></SfListBox>

@code {
    public string[] Items = new string[] { "Apple", "Banana", "Orange", "Mango", "Grape" };
}

With data binding:

<SfListBox TValue="string[]" DataSource="@Vehicles" TItem="VehicleData">
    <ListBoxFieldSettings Text="Text" Value="Id" />
</SfListBox>

@code {
    public List<VehicleData> Vehicles = new List<VehicleData>
    {
        new VehicleData { Text = "Hennessey Venom", Id = "Vehicle-01" },
        new VehicleData { Text = "Bugatti Chiron", Id = "Vehicle-02" },
        new VehicleData { Text = "McLaren F1", Id = "Vehicle-03" }
    };

    public class VehicleData
    {
        public string Text { get; set; }
        public string Id { get; set; }
    }
}

Key Props & Events

Important Properties:

DataSource - Array or list of items to display
TValue - Type of selected values (string[], int[], etc.)
TItem - Type of data source items
Value - Currently selected values (two-way bindable)
MaximumSelectionLength - Limit number of selections (default: 500)
Enabled - Enable/disable the component
AllowFiltering - Enable search/filter functionality
Allowdragging - Enable drag-and-drop reordering

Selection Settings:

Mode - SelectionMode.Single or SelectionMode.Multiple
ShowCheckbox - Show checkboxes for selection
ShowSelectAll - Show "Select All" checkbox

Common Events:

ValueChange - Fires when selected values change
Change - Fires on item selection change
Select - Fires when item is selected

Common Patterns

1. Single Selection Mode

<ListBoxSelectionSettings Mode="Syncfusion.Blazor.DropDowns.SelectionMode.Single" />

2. Multiple Selection with Checkboxes

<ListBoxSelectionSettings ShowCheckbox="true" ShowSelectAll="true" />

3. Getting Selected Values

@bind-Value="@SelectedValues"

@code {
    public string[] SelectedValues { get; set; }
}

4. Handling Selection Change

<SfListBox ValueChange="@OnSelectionChanged" ...>
</SfListBox>

@code {
    private void OnSelectionChanged(ChangeEventArgs args)
    {
        var selectedValues = args.Value as string[];
        // Process selected values
    }
}

5. Filtering Enabled

<SfListBox AllowFiltering="true" FilterType="FilterType.Contains" ... >
</SfListBox>

Documentation & Navigation Guide

Choose the reference that matches your current task:

Getting Started

📄 Read: references/getting-started.md

Installation and NuGet package setup
Project configuration (WebAssembly, Server, Web App)
Basic component markup and first example
Theme configuration and stylesheets
Running and testing your first ListBox

Data Binding

📄 Read: references/data-binding.md

Binding array of strings
Binding array of objects with field mapping
Binding complex nested objects
Remote data loading with DataManager
Dynamic data updates
Best practices for data binding

Selection & Modes

📄 Read: references/selection-and-modes.md

Single selection configuration
Multiple selection (default mode)
Checkbox selection with ShowCheckbox
Select All functionality
Getting selected items and values
MaximumSelectionLength constraints
Selection change events
Common selection patterns

Features & Interactions

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

Filtering and search capabilities
Drag-and-drop reordering (Allowdragging)
Item enable/disable functionality
Icons and icon CSS classes
Item templates for custom rendering
Sorting and grouping data
Dual ListBox pattern (source to target)
Accessibility attributes

Styling & Appearance

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

Theme application (Bootstrap, Material, Fluent, Tailwind)
CSS class customization
Custom item templates for styling
Icon integration and styling
Dark mode implementation
Responsive design patterns
Layout and sizing

Accessibility & Events

📄 Read: references/accessibility-and-events.md

WCAG 2.1 compliance guidelines
Keyboard navigation support
ARIA labels and roles
Event binding (ValueChange, Change, Select)
Event handling patterns
Focus management
Screen reader support
Common accessibility patterns

Use Case Examples

Choose a reference based on your scenario:

"I need to add a ListBox to my Blazor project" → Getting Started
"How do I bind data to ListBox?" → Data Binding
"I want users to select multiple items with checkboxes" → Selection & Modes
"Can I let users search/filter the list?" → Features & Interactions
"How do I customize colors and styling?" → Styling & Appearance
"Does ListBox support keyboard navigation?" → Accessibility & Events
"I need a source/target ListBox pattern" → Features & Interactions

Next Steps

New to ListBox? Start with Getting Started
Have data to bind? Go to Data Binding
Need multi-selection? Check Selection & Modes
Want advanced features? Explore Features & Interactions
Making it look good? Read Styling & Appearance
Accessibility needed? Review Accessibility & Events

syncfusion-blazor-dropdowns

Implementing Syncfusion Blazor Dropdowns

AutoComplete

Component Overview

Documentation Navigation Guide

Getting Started

Data Binding & Sources

Filtering & Search

Data Organization

Templates & Styling

Advanced Features

Accessibility & Best Practices

Quick Start Example

Common Patterns

Pattern 1: Filtering User Input

Pattern 2: Remote Data with Debounce

Pattern 3: Custom Item Display with Templates

Pattern 4: Grouped & Sorted Display

Key Props

Common Use Cases

ComboBox

When to Use This Skill

Quick Start Example

Key Props Reference

Common Patterns

Pattern 1: Basic Data Binding

Pattern 2: Filtering & Search

Pattern 3: Cascading ComboBox

Pattern 4: Form Integration

Pattern 5: Custom Templates

Documentation Navigation Guide

📄 Getting Started

📄 Data Binding

📄 Filtering & Search

📄 Selection & Value Binding

📄 Cascading ComboBox

📄 Templates & Customization

📄 Events & Validation

📄 Popup & Appearance

📄 Advanced Features

📄 Troubleshooting

Common Use Cases

Key Features Summary

Related Components

DropDown List

When to Use This Skill

Component Overview

Documentation and Navigation Guide

Getting Started

Data Binding

Filtering and Searching

Templates and Rendering

Selection and Value Binding

Customization and Styling

Advanced Features

Form Validation

Localization and RTL

Accessibility

Quick Start

Basic Dropdown Implementation

With Value Binding and Selection Event

Common Patterns

Pattern 1: Dropdown with Filtering

Pattern 2: Cascading Dropdowns

Pattern 3: Remote Data Binding

Pattern 4: Custom Item Template

Pattern 5: Form Validation

Key Props and Events

Essential Properties

Essential Events (inside <DropDownListEvents>)

Common Use Cases

Related Components

Next Steps

MultiSelect Dropdown

When to Use This Skill

Component Overview

Documentation and Navigation Guide

Getting Started

Data Binding

Features and Selection

Essential Events (inside `<DropDownListEvents>`)