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

• 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

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

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"
</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

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

Essential Events (inside <DropDownListEvents>)

Common Use Cases

1. User Selection in Forms - Select users from a list for assignment or notification
2. Category/Type Selection - Choose from predefined categories or types
3. Cascading Selections - Dependent dropdowns (Country → State → City)
4. Dynamic Data from APIs - Load options from backend services
5. Searchable Lists - Filter through large datasets efficiently
6. Multi-stage Workflows - Selection-based form navigation
7. Data Filtering - Apply filters based on dropdown selection
8. Templated Dropdowns - Display rich content (images, descriptions)
9. Localized Selections - Region/language-specific options
10. 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

1. Choose your use case from "Common Use Cases" above
2. Navigate to the relevant reference guide in the "Documentation and Navigation Guide" section
3. Copy the pattern example and adapt it to your specific data and requirements
4. 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 TValue="string[]" 
               TItem="EmployeeData"
               DataSource="@Employees"
               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 TValue="string[]" 
                   TItem="ItemData"
                   DataSource="@Items"
                   @bind-Value="SelectedValues"
                   Placeholder="Select items">
        <MultiSelectFieldSettings Text="Name" Value="ID"></MultiSelectFieldSettings>
    </SfMultiSelect>
</div>

@code {
    private string[] SelectedValues { get; set; } = Array.Empty<string>();
    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 TValue="string[]" 
               TItem="RemoteItem"
               DataSource="@RemoteData"
               AllowFiltering="true"
               Mode="VisualMode.CheckBox"
               Placeholder="Search and select">
    <MultiSelectFieldSettings Text="Text" Value="ID"></MultiSelectFieldSettings>
    <MultiSelectEvents TValue="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"
    <DataAnnotationsValidator />
    
    <div class="form-group">
        <label>Select at least 2 items:</label>
        <SfMultiSelect TValue="string[]"
                       TItem="ItemData"
                       DataSource="@Items"
                       @bind-Value="FormData.SelectedItems"
                       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 string[] SelectedItems { get; set; } = Array.Empty<string>();
    }

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

Key Props Reference

…(truncated)