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

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" OnValidSubmit="HandleSubmit">
    <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

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="@MentionCharAt">
    <TargetComponent>
        <div id="comments" contenteditable="true" placeholder="Type @ to mention..."></div>
    </TargetComponent>
    <ChildContent>
        <MentionFieldSettings Text="UserName"></MentionFieldSettings>
    </ChildContent>
</SfMention>

@code {
    private char MentionCharAt = '@';
}

Pattern 2: Filtered Suggestions with Remote Data

<SfMention TItem="EmployeeData" MentionChar="@MentionCharAt" MinLength="2" FilterType="FilterType.StartsWith">
    <TargetComponent>
        <input id="employeeInput" type="text" placeholder="Search employees..." />
    </TargetComponent>
    <ChildContent>
        <SfDataManager Url="YOUR_API_ENDPOINT" Adaptor="Adaptors.WebApiAdaptor"></SfDataManager>
        <MentionFieldSettings Text="Name"></MentionFieldSettings>
    </ChildContent>
</SfMention>

@code {
    private char MentionCharAt = '@';
}

Pattern 3: Custom Display with Templates

<SfMention TItem="PersonData" DataSource="@TeamMembers" MentionChar="@MentionCharAt">
    <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>

@code {
    private char MentionCharAt = '@';
}

---

Key Properties

---

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

1. Start here: Read Getting Started to install and set up 2. Bind data: Learn Working with Data for local/remote sources 3. Enhance UX: Explore Filtering & Search and Templates 4. Ensure accessibility: Review Accessibility for inclusive design 5. 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

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

Accessibility & Best Practices for Syncfusion Blazor AutoComplete

WCAG Compliance

The AutoComplete component is built with accessibility standards in mind. Ensure your implementation follows these guidelines:

Semantic HTML

Use proper semantic structure in templates:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees">
    <AutoCompleteFieldSettings Value="EmployeeName">
    </AutoCompleteFieldSettings>
    <AutoCompleteTemplates TItem="Employee">
        <ItemTemplate>
            <div role="option">
                @((context as Employee)?.EmployeeName)
                <span aria-label="Department: @((context as Employee)?.Department)">
                    @((context as Employee)?.Department)
                </span>
            </div>
        </ItemTemplate>
    </AutoCompleteTemplates>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public string Department { get; set; }
    }

    private List<Employee> Employees = new();
}

ARIA Attributes

Provide context for assistive technologies:

Basic ARIA Labels

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                Placeholder="Choose country">
</SfAutoComplete>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
}

ARIA Expanded & Popup

@using Syncfusion.Blazor.DropDowns

<div role="combobox" 
     aria-label="Country selector"
     aria-expanded="@PopupOpen"
     aria-haspopup="listbox">
    <SfAutoComplete TValue="string" TItem="string" 
                    DataSource="@Countries">
        <AutoCompleteEvents TValue="string" TItem="string"
                            Opened="@OnOpened"
                            Closed="@OnClosed">
        </AutoCompleteEvents>
    </SfAutoComplete>
</div>

@code {
    private bool PopupOpen = false;
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };

    private void OnOpened(PopupEventArgs args) => PopupOpen = true;
    private void OnClosed(ClosedEventArgs args) => PopupOpen = false;
}

Group Accessibility

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees">
    <AutoCompleteFieldSettings Value="EmployeeName" GroupBy="Department">
    </AutoCompleteFieldSettings>
    <AutoCompleteTemplates TItem="Employee">
        <GroupTemplate>
            <div role="group" aria-label="@((context as CompositeData)?.GroupData?.Key) Department">
                @((context as CompositeData)?.GroupData?.Key)
            </div>
        </GroupTemplate>
    </AutoCompleteTemplates>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public string Department { get; set; }
    }

    private List<Employee> Employees = new();
}

Keyboard Navigation

Keyboard Support (Built-in)

The AutoComplete supports these keyboard interactions by default:

Test Keyboard Navigation

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true">
</SfAutoComplete>

<p>Keyboard Tips:</p>
<ul>
    <li>Use Arrow Up/Down to navigate items</li>
    <li>Press Enter to select</li>
    <li>Press Escape to close</li>
    <li>Type to filter items</li>
</ul>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada", "Denmark", "Egypt" 
    };
}

Screen Reader Support

Announce Item Selection

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries">
    <AutoCompleteEvents TValue="string" TItem="string"
                        OnValueSelect="@OnItemSelected">
    </AutoCompleteEvents>
</SfAutoComplete>

<div role="status" aria-live="polite" aria-atomic="true">
    @AnnouncementMessage
</div>

@code {
    private string AnnouncementMessage = "";
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };

    private void OnItemSelected(SelectEventArgs<string> args)
    {
        AnnouncementMessage = $"Selected: {args.ItemData}";
    }
}

Live Region for Filtering

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true">
    <AutoCompleteEvents TValue="string" TItem="string"
                        Filtering="@OnFiltering">
    </AutoCompleteEvents>
</SfAutoComplete>

<div role="region" aria-live="assertive" aria-atomic="true">
    @FilterMessage
</div>

@code {
    private string FilterMessage = "";
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada", "Denmark", "Egypt" 
    };

    private void OnFiltering(FilteringEventArgs args)
    {
        var matchCount = Countries.Count(c => c.Contains(args.Text, StringComparison.OrdinalIgnoreCase));
        FilterMessage = $"{matchCount} items match '{args.Text}'";
    }
}

Color Contrast

Ensure sufficient contrast for readability:

<SfAutoComplete TItem="string" 
                DataSource="@Countries"
                CssClass="accessible-autocomplete">
</SfAutoComplete>

<style>
    /* WCAG AA compliance: 4.5:1 contrast ratio for normal text */
    .accessible-autocomplete.e-autocomplete .e-input {
        color: #000;  /* Black text */
        background: #fff;  /* White background */
        border: 1px solid #333;  /* Dark border */
    }

    /* WCAG AAA compliance: 7:1 contrast ratio */
    .accessible-autocomplete.e-autocomplete .e-list-item {
        color: #000;
        background: #fff;
    }

    .accessible-autocomplete.e-autocomplete .e-list-item:focus,
    .accessible-autocomplete.e-autocomplete .e-list-item.e-item-focus {
        background: #003d7a;  /* High contrast blue */
        color: #fff;
    }
</style>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
}

Focus Indicators

Make focus visible for keyboard navigation:

<SfAutoComplete TItem="string" 
                DataSource="@Countries"
                CssClass="accessible-focus">
</SfAutoComplete>

<style>
    /* Clear focus indicator */
    .accessible-focus.e-autocomplete .e-input:focus {
        outline: 3px solid #004085;
        outline-offset: 2px;
    }

    .accessible-focus.e-autocomplete .e-list-item:focus {
        outline: 2px solid #004085;
    }
</style>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
}

Label Association

Always associate a label with the AutoComplete:

@using Syncfusion.Blazor.DropDowns

<label for="country-select">Country of Residence</label>
<SfAutoComplete TItem="string" 
                DataSource="@Countries"
                Id="country-select"
                FloatLabelType="FloatLabelType.Always"
                Placeholder="Select country">
</SfAutoComplete>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
}

Error Messages & Validation

Display accessible error states:

@using Syncfusion.Blazor.DropDowns

<div>
    <label for="email-country">Country</label>
    <SfAutoComplete TValue="string" TItem="string" 
                    DataSource="@Countries"
                    Id="email-country"
                    @bind-Value="SelectedCountry">
        <AutoCompleteEvents TValue="string" TItem="string"
                            ValueChange="@OnCountryChange">
        </AutoCompleteEvents>
    </SfAutoComplete>
    
    @if (!IsValid)
    {
        <div id="error-message" role="alert" style="color: #dc3545; margin-top: 5px;">
            ⚠️ Please select a valid country
        </div>
    }
</div>

@code {
    private string SelectedCountry = "";
    private bool IsValid = true;
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };

    private void OnCountryChange(ChangeEventArgs<string, string> args)
    {
        SelectedCountry = args.Value;
        IsValid = !string.IsNullOrEmpty(args.Value);
    }
}

Best Practices

1. Provide Clear Instructions

<div>
    <h3>Search for Products</h3>
    <p>Start typing the product name. Use arrow keys to navigate results.</p>
    <SfAutoComplete TValue="string" TItem="string" 
                    DataSource="@Products">
    </SfAutoComplete>
</div>

@code {
    private List<string> Products = new();
}

2. Handle Empty States

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true">
    <AutoCompleteTemplates TItem="string">
        <NoRecordsTemplate>
            <div role="alert">
                <p>No results found. Try a different search term.</p>
            </div>
        </NoRecordsTemplate>
    </AutoCompleteTemplates>
</SfAutoComplete>

@code {
    private List<string> Countries = new();
}

3. Performance Optimization

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees"
                AllowFiltering="true"
                MinLength="2"
                DebounceDelay="300"
                EnableVirtualization="true">
    <AutoCompleteFieldSettings Value="EmployeeName"></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
    }

    private List<Employee> Employees = new();
    
    protected override void OnInitialized()
    {
        // Load large dataset efficiently
        for (int i = 1; i <= 10000; i++)
        {
            Employees.Add(new Employee 
            { 
                EmployeeId = i, 
                EmployeeName = $"Employee {i}" 
            });
        }
    }
}

4. Mobile-Friendly Design

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                CssClass="mobile-optimized"
                PopupHeight="400px"
                PopupWidth="100%">
</SfAutoComplete>

<style>
    @media (max-width: 768px)
    {
        .mobile-optimized.e-autocomplete .e-input {
            font-size: 16px;  /* Prevents zoom on iOS */
            padding: 12px;
        }

        .mobile-optimized.e-autocomplete .e-list-item {
            padding: 12px;
            min-height: 44px;  /* Touch-friendly size */
        }
    }
</style>

@code {
    private List<string> Countries = new();
}

Troubleshooting

Issue: Screen Reader Not Reading Items

Solution: Ensure proper ARIA labels and roles:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries">
</SfAutoComplete>

Issue: Keyboard Navigation Not Working

Solution: Verify focus is properly managed:

@if (FocusOnFirst)
{
    <SfAutoComplete TValue="string" TItem="string" 
                    DataSource="@Countries"
                    @ref="AutoCompleteRef">
    </SfAutoComplete>
}

@code {
    private bool FocusOnFirst = false;
    private SfAutoComplete<string, string> AutoCompleteRef;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            FocusOnFirst = true;
            await AutoCompleteRef.FocusAsync();
        }
    }
}

Related Topics

• Templates & Styling
• Advanced Features
• Getting Started

Advanced Features in Syncfusion Blazor AutoComplete

Virtualization

For large datasets (100+ items), use virtualization to render only visible items, improving performance:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                EnableVirtualization="true"
                Placeholder="Select a country">
</SfAutoComplete>

@code {
    private List<string> Countries = new();

    protected override void OnInitialized()
    {
        // Generate 1000 items
        for (int i = 1; i <= 1000; i++)
        {
            Countries.Add($"Country {i}");
        }
    }
}

Benefits:

• Handles 1000s of items without performance degradation
• Only renders visible items in viewport
• Smooth scrolling and instant filtering

Virtualization with Objects

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees"
                AllowFiltering="true"
                EnableVirtualization="true">
    <AutoCompleteFieldSettings Value="EmployeeName" >
    </AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public string Department { get; set; }
    }

    private List<Employee> Employees = new();

    protected override void OnInitialized()
    {
        // Generate 5000 employees
        for (int i = 1; i <= 5000; i++)
        {
            Employees.Add(new Employee 
            { 
                EmployeeId = i, 
                EmployeeName = $"Employee {i}", 
                Department = $"Dept {(i % 10)}"
            });
        }
    }
}

Popup Settings

Control the appearance and behavior of the dropdown popup:

Positioning

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                PopupHeight="200px"
                PopupWidth="300px">
</SfAutoComplete>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada", "Denmark" 
    };
}

Properties:

• PopupHeight - Height of dropdown (default: auto)
• PopupWidth - Width of dropdown (default: matches input width)

Popup Open/Close Events

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries">
    <AutoCompleteEvents TValue="string" TItem="string"
                        Opened="@OnPopupOpen"
                        Closed="@OnPopupClose">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>Popup State: @PopupState</p>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
    
    private string PopupState = "Closed";

    private void OnPopupOpen(PopupEventArgs args)
    {
        PopupState = "Opened";
        Console.WriteLine("Popup opened");
    }

    private void OnPopupClose(ClosedEventArgs args)
    {
        PopupState = "Closed";
        Console.WriteLine("Popup closed");
    }
}

Disabled Items

Prevent users from selecting specific items:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees">
    <AutoCompleteFieldSettings Value="EmployeeName" Disabled="IsDisabled">
    </AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public bool IsDisabled { get; set; }
    }

    private List<Employee> Employees = new()
    {
        new Employee { EmployeeId = 1, EmployeeName = "John Smith", IsDisabled = false },
        new Employee { EmployeeId = 2, EmployeeName = "Jane Doe", IsDisabled = true },  // Disabled
        new Employee { EmployeeId = 3, EmployeeName = "Bob Wilson", IsDisabled = false }
    };
}

Result: "Jane Doe" appears grayed out and cannot be selected.

Custom Values

Allow users to enter values not in the original dataset:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowCustom="true"
                Placeholder="Select or type a country">
</SfAutoComplete>

<p>Selected: @SelectedValue</p>

@code {
    private string SelectedValue = "";
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
}

Behavior: If user types "France", the value "France" is retained even though it's not in the list.

Custom Values with Validation

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowCustom="true"
                @bind-Value="CustomValue"
                Placeholder="Enter a country">
    <AutoCompleteEvents TValue="string" TItem="string"
                        ValueChange="@OnValueChange">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>@ValidationMessage</p>

@code {
    private string CustomValue = "";
    private string ValidationMessage = "";
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };

    private void OnValueChange(ChangeEventArgs<string, string> args)
    {
        CustomValue = args.Value;
        
        if (string.IsNullOrEmpty(args.Value))
        {
            ValidationMessage = "";
        }
        else if (args.Value.Length < 2)
        {
            ValidationMessage = "Country name must be at least 2 characters";
        }
        else
        {
            ValidationMessage = $"✓ {args.Value} is valid";
        }
    }
}

Localization & RTL

Right-to-Left (RTL) Support

Enable RTL for languages like Arabic, Hebrew:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                EnableRtl="true"
                Placeholder="اختر دولة">
</SfAutoComplete>

@code {
    private List<string> Countries = new() 
    { 
        "مصر", "السعودية", "الإمارات" 
    };
}

Common Locales: en (English), es (Spanish), fr (French), de (German), ar (Arabic)

Event Handling

ValueChange Event

Triggered when user selects or enters a value:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                @bind-Value="SelectedValue">
    <AutoCompleteEvents TValue="string" TItem="string"
                        ValueChange="@OnValueChange">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>Selected: @SelectedValue</p>
<p>Change Count: @ChangeCount</p>

@code {
    private string SelectedValue = "";
    private int ChangeCount = 0;
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };

    private void OnValueChange(ChangeEventArgs<string, string> args)
    {
        SelectedValue = args.Value;
        ChangeCount++;
        Console.WriteLine($"Value changed to: {args.Value}");
    }
}

Focus & Blur Events

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries">
    <AutoCompleteEvents TValue="string" TItem="string"
                        Focus="@OnFocus"
                        Blur="@OnBlur">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>Status: @Status</p>

@code {
    private string Status = "Not focused";
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };

    private void OnFocus(object args)
    {
        Status = "Focused";
    }

    private void OnBlur(object args)
    {
        Status = "Blurred";
    }
}

Filtering Event

Execute custom logic during filtering:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees"
                AllowFiltering="true">
    <AutoCompleteFieldSettings Value="EmployeeName" >
    </AutoCompleteFieldSettings>
    <AutoCompleteEvents TValue="string" TItem="Employee"
                        Filtering="@OnFiltering">
    </AutoCompleteEvents>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public string Department { get; set; }
    }

    private List<Employee> Employees = new()
    {
        new Employee { EmployeeId = 1, EmployeeName = "John Smith", Department = "IT" },
        new Employee { EmployeeId = 2, EmployeeName = "Jane Doe", Department = "HR" },
        new Employee { EmployeeId = 3, EmployeeName = "Bob Wilson", Department = "IT" }
    };

    private void OnFiltering(FilteringEventArgs args)
    {
        Console.WriteLine($"Filtering for: {args.Text}");
        
        // Custom filter: only show IT department
        args.FilteredData = Employees
            .Where(e => e.Department == "IT" && e.EmployeeName.Contains(args.Text))
            .Cast<object>()
            .ToList();
    }
}

Selection Event

Execute logic when user selects an item:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Product" 
                DataSource="@Products">
    <AutoCompleteFieldSettings Value="ProductName" >
    </AutoCompleteFieldSettings>
    <AutoCompleteEvents TValue="string" TItem="Product"
                        OnValueSelect="@OnItemSelected">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>@SelectionMessage</p>

@code {
    public class Product
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
        public decimal Price { get; set; }
    }

    private string SelectionMessage = "";
    
    private List<Product> Products = new()
    {
        new Product { ProductId = 1, ProductName = "Laptop", Price = 999 },
        new Product { ProductId = 2, ProductName = "Mouse", Price = 29 }
    };

    private void OnItemSelected(SelectEventArgs<Product> args)
    {
        SelectionMessage = $"You selected: {args.ItemData.ProductName} (${args.ItemData.Price})";
        Console.WriteLine($"Selected Product ID: {args.ItemData.ProductId}");
    }
}

Common Patterns

Pattern 1: Search with API Call

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="GitHubUser" 
                AllowFiltering="true"
                DebounceDelay="500">
    <AutoCompleteFieldSettings Value="Login" >
    </AutoCompleteFieldSettings>
    <AutoCompleteEvents TValue="string" TItem="GitHubUser"
                        Filtering="@OnFiltering">
    </AutoCompleteEvents>
</SfAutoComplete>

@code {
    public class GitHubUser
    {
        public string Login { get; set; }
    }

    private List<GitHubUser> SearchResults = new();

    private async Task OnFiltering(FilteringEventArgs args)
    {
        if (string.IsNullOrEmpty(args.Text) || args.Text.Length < 2)
        {
            args.FilteredData = new();
            return;
        }

        try
        {
            using var client = new HttpClient();
            var response = await client.GetAsync($"YOUR_API_ENDPOINT/search/users?q={args.Text}&per_page=5");
            // Parse response and populate args.FilteredData
        }
        catch { }
    }
}

Pattern 2: Dependent AutoComplete

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Country" 
                DataSource="@Countries"
                @bind-Value="SelectedCountry">
    <AutoCompleteFieldSettings Value="CountryName" ></AutoCompleteFieldSettings>
    <AutoCompleteEvents TValue="string" TItem="Country"
                        ValueChange="@OnCountryChange">
    </AutoCompleteEvents>
</SfAutoComplete>

<SfAutoComplete TValue="string" TItem="City" 
                DataSource="@Cities"
                @bind-Value="SelectedCity">
    <AutoCompleteFieldSettings Value="CityName" ></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Country { public string CountryName { get; set; } }
    public class City { public string CityName { get; set; } public string Country { get; set; } }

    private string SelectedCountry = "";
    private string SelectedCity = "";

    private List<Country> Countries = new()
    {
        new Country { CountryName = "USA" },
        new Country { CountryName = "Canada" }
    };

    private List<City> Cities = new();
    private List<City> AllCities = new()
    {
        new City { CityName = "New York", Country = "USA" },
        new City { CityName = "Los Angeles", Country = "USA" },
        new City { CityName = "Toronto", Country = "Canada" }
    };

    private void OnCountryChange(ChangeEventArgs<string, Country> args)
    {
        SelectedCountry = args.Value;
        // Filter cities based on selected country
        Cities = AllCities.Where(c => c.Country == SelectedCountry).ToList();
        SelectedCity = "";
    }
}

Related Topics

• Filtering & Search
• Templates & Styling
• Accessibility & Best Practices

Data Binding in Syncfusion Blazor AutoComplete

Table of Contents

• Overview
• Binding Local Data
• Primitive Types
• Object Collections
• ObservableCollection
• Dynamic Objects
• Remote Data
• Web API
• OData Services
• Custom Adaptor
• DataBound Event

Overview

The AutoComplete component loads data through the DataSource property. It supports multiple data source types:

• Arrays and Lists of primitives (string, int, etc.)
• Collections of objects
• Remote services (Web APIs, OData)
• Dynamic objects (ExpandoObject, DynamicObject)
• ObservableCollection for real-time updates

Binding Local Data

Primitive Types

Bind arrays or lists of simple data types like strings and integers.

String Array:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                Placeholder="Select a country">
</SfAutoComplete>

@code {
    private List<string> Countries = new()
    {
        "Austria",
        "Brazil", 
        "Canada",
        "Denmark",
        "Egypt",
        "Finland"
    };
}

Integer Array:

<SfAutoComplete TValue="int" TItem="int" 
                DataSource="@Numbers"
                Placeholder="Select a number">
</SfAutoComplete>

@code {
    private List<int> Numbers = new() { 10, 20, 30, 40, 50 };
}

Object Collections

Map object properties to AutoComplete fields using AutoCompleteFieldSettings.

Basic Object Binding:

<SfAutoComplete TValue="string" TItem="Country" 
                DataSource="@Countries"
                Placeholder="Select a country">
    <AutoCompleteFieldSettings Value="CountryName"></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Country
    {
        public string CountryName { get; set; }
        public string Code { get; set; }
    }

    private List<Country> Countries = new()
    {
        new Country { CountryName = "Austria", Code = "AT" },
        new Country { CountryName = "Brazil", Code = "BR" },
        new Country { CountryName = "Canada", Code = "CA" }
    };
}

Complex Object with Display Text:

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees"
                Placeholder="Select an employee">
    <AutoCompleteFieldSettings Value="EmployeeName" >
    </AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public string Department { get; set; }
    }

    private List<Employee> Employees = new()
    {
        new Employee { EmployeeId = 1, EmployeeName = "John Smith", Department = "IT" },
        new Employee { EmployeeId = 2, EmployeeName = "Jane Doe", Department = "HR" },
        new Employee { EmployeeId = 3, EmployeeName = "Bob Wilson", Department = "Sales" }
    };
}

ObservableCollection

Use ObservableCollection when you need to dynamically add or remove items and have the UI update automatically.

@using Syncfusion.Blazor.DropDowns
@using System.Collections.ObjectModel

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                Placeholder="Select a country">
</SfAutoComplete>

<button @onclick="AddCountry">Add Country</button>

@code {
    private ObservableCollection<string> Countries = new()
    {
        "Austria",
        "Brazil",
        "Canada"
    };

    private void AddCountry()
    {
        Countries.Add("Denmark");
    }
}

Dynamic Objects

ExpandoObject:

@using Syncfusion.Blazor.DropDowns
@using System.Dynamic

<SfAutoComplete TValue="string" TItem="dynamic" 
                DataSource="@DynamicCountries"
                Placeholder="Select a country">
    <AutoCompleteFieldSettings Value="CountryName"></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    private List<dynamic> DynamicCountries = new();

    protected override void OnInitialized()
    {
        DynamicCountries = new()
        {
            CreateDynamic("Austria", "AT"),
            CreateDynamic("Brazil", "BR"),
            CreateDynamic("Canada", "CA")
        };
    }

    private dynamic CreateDynamic(string name, string code)
    {
        dynamic obj = new ExpandoObject();
        obj.CountryName = name;
        obj.CountryCode = code;
        return obj;
    }
}

Remote Data

Web API

Fetch data from a Web API endpoint using SfDataManager:

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

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true"
                DebounceDelay="300">
    <SfDataManager Url="YOUR_API_ENDPOINT" 
                   Adaptor="Syncfusion.Blazor.Adaptors.UrlAdaptor">
    </SfDataManager>
    <AutoCompleteFieldSettings Value="ProductName" ></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Product
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
        public decimal Price { get; set; }
    }
}

OData Services

Connect to OData endpoints like SharePoint or Azure Data Services:

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

<SfAutoComplete TValue="string" TItem="Order" 
                AllowFiltering="true"
                DebounceDelay="300">
    <SfDataManager Url="YOUR_ODATA_SERVICE_URL" 
                   Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor">
    </SfDataManager>
    <AutoCompleteFieldSettings Value="CustomerID"></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Order
    {
        public int OrderID { get; set; }
        public string CustomerID { get; set; }
        public DateTime OrderDate { get; set; }
    }
}

With Query Filter:

<SfAutoComplete TValue="string" TItem="Order" 
                AllowFiltering="true">
    <SfDataManager Url="YOUR_ODATA_SERVICE_URL" 
                   Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor">
        <SfDataManagerRequest PageSize="10"></SfDataManagerRequest>
    </SfDataManager>
</SfAutoComplete>

Custom Adaptor

For custom data sources or business logic:

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

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true">
    <SfDataManager AdaptorInstance="@typeof(CustomAdaptor)">
    </SfDataManager>
</SfAutoComplete>

@code {
    public class CustomAdaptor : DataAdaptor
    {
        public override async Task<Object> Read(DataManagerRequest dm, string key = null)
        {
            // Call your API or database here
            var products = await GetProductsAsync();
            
            // Handle filtering if dm.Search contains search text
            if (dm.Search != null && dm.Search.Count > 0)
            {
                var searchKey = dm.Search[0];
                products = products.Where(p => p.ProductName.Contains(searchKey)).ToList();
            }
            
            return products;
        }

        private async Task<List<Product>> GetProductsAsync()
        {
            // Fetch from your API
            return new() { /* ... */ };
        }
    }

    public class Product
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
    }
}

DataBound Event

The DataBound event fires after data is loaded into the AutoComplete. Use it to perform post-processing or notifications:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries">
    <AutoCompleteEvents TValue="string" TItem="string"
                        DataBound="@OnDataBound">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>@LoadMessage</p>

@code {
    private List<string> Countries = new() { "Austria", "Brazil", "Canada" };
    private string LoadMessage = "";

    private void OnDataBound(DataBoundEventArgs args)
    {
        LoadMessage = "Data loaded successfully";
    }
}

Best Practices

1. Use DebounceDelay for Remote Data: Reduce server requests by adding a delay before filter requests 2. Lazy Load Large Datasets: Use pagination or virtualization instead of loading all data at once 3. Map Fields Explicitly: Always use AutoCompleteFieldSettings to clarify which property is the display value 4. Handle Null Values: Check for null before accessing nested properties in complex objects 5. Use ObservableCollection for Dynamic Updates: When items change after initial load, use ObservableCollection for automatic UI updates

Related Topics

• Filtering & Search
• Templates & Styling
• Advanced Features

Data Organization in Syncfusion Blazor AutoComplete

Grouping Data

Organize list items into categories using AllowGrouping and the GroupBy field:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees"
                Placeholder="Select an employee">
    <AutoCompleteFieldSettings Value="EmployeeName"  GroupBy="Department"></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public string Department { get; set; }
    }

    private List<Employee> Employees = new()
    {
        new Employee { EmployeeId = 1, EmployeeName = "John Smith", Department = "IT" },
        new Employee { EmployeeId = 2, EmployeeName = "Jane Doe", Department = "IT" },
        new Employee { EmployeeId = 3, EmployeeName = "Bob Wilson", Department = "HR" },
        new Employee { EmployeeId = 4, EmployeeName = "Alice Brown", Department = "HR" }
    };
}

Result: Employees are grouped by Department (IT, HR), with group headers shown in the dropdown.

Customizing Group Headers

Use GroupTemplate to create custom group header displays:

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees">
    <AutoCompleteFieldSettings Value="EmployeeName" GroupBy="Department"></AutoCompleteFieldSettings>
    <AutoCompleteTemplates TItem="Employee">
        <GroupTemplate>
            <div style="padding: 10px; background: #f0f0f0; font-weight: bold;">
                @((context as CompositeData)?.GroupData?.Key)
            </div>
        </GroupTemplate>
    </AutoCompleteTemplates>
</SfAutoComplete>

Sorting Options

Control the order of list items using SortOrder:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                SortOrder="SortOrder.Ascending"
                Placeholder="Select a country">
</SfAutoComplete>

@code {
    private List<string> Countries = new() 
    { 
        "Brazil", "Austria", "Canada", "Denmark", "Egypt" 
    };
}

SortOrder Options:

• Ascending - Alphabetical A-Z
• Descending - Reverse Z-A
• None - Original order (default)

Sorting Complex Objects

Sorting applies to the display field (Text):

<SfAutoComplete TValue="string" TItem="Product" 
                DataSource="@Products"
                SortOrder="SortOrder.Ascending">
    <AutoCompleteFieldSettings Value="ProductName" ></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Product
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
    }

    private List<Product> Products = new()
    {
        new Product { ProductId = 1, ProductName = "Zebra" },
        new Product { ProductId = 2, ProductName = "Apple" },
        new Product { ProductId = 3, ProductName = "Mango" }
    };
}

Result: Display order is Apple, Mango, Zebra (sorted by ProductName).

Multicolumn Display

Display multiple columns of data in the dropdown using ItemTemplate:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Product" 
                DataSource="@Products"
                Placeholder="Search products">
    <AutoCompleteFieldSettings Value="ProductName"></AutoCompleteFieldSettings>
    <AutoCompleteTemplates TItem="Product">
        <ItemTemplate>
            <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 10px;">
                <span>@((context as Product)?.ProductName)</span>
                <span>@((context as Product)?.Category)</span>
                <span style="text-align: right;">@((context as Product)?.Price)</span>
            </div>
        </ItemTemplate>
    </AutoCompleteTemplates>
</SfAutoComplete>

@code {
    public class Product
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }

    private List<Product> Products = new()
    {
        new Product { ProductId = 1, ProductName = "Laptop", Category = "Electronics", Price = 999 },
        new Product { ProductId = 2, ProductName = "Mouse", Category = "Electronics", Price = 29 },
        new Product { ProductId = 3, ProductName = "Desk", Category = "Furniture", Price = 199 }
    };
}

Result: Each dropdown item shows three columns: Name, Category, Price.

Header Template for Multicolumn

Add column headers to multicolumn displays:

<SfAutoComplete TValue="string" TItem="Product" 
                DataSource="@Products">
    <AutoCompleteFieldSettings Value="ProductName" 
                               Text="ProductName">
    </AutoCompleteFieldSettings>
    <AutoCompleteTemplates TItem="Product">
        <HeaderTemplate>
            <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 10px; 
                        padding: 10px; background: #f5f5f5; font-weight: bold;">
                <span>Product</span>
                <span>Category</span>
                <span style="text-align: right;">Price</span>
            </div>
        </HeaderTemplate>
        <ItemTemplate>
            <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 10px;">
                <span>@((context as Product)?.ProductName)</span>
                <span>@((context as Product)?.Category)</span>
                <span style="text-align: right;">@((context as Product)?.Price)</span>
            </div>
        </ItemTemplate>
    </AutoCompleteTemplates>
</SfAutoComplete>

Selection Modes

Control how users interact with list items.

Standard Selection

Single item selection (default):

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                Placeholder="Select a country">
</SfAutoComplete>

Read-Only Selection

Prevent manual input, force selection from list:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="false">
</SfAutoComplete>

Custom Value Entry

Allow users to enter values not in the list:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowCustom="true"
                Placeholder="Select or type a country">
</SfAutoComplete>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
}

Behavior: User can type "France" even if it's not in the list. The custom value is retained.

Selection Event

React to user selections:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries">
    <AutoCompleteEvents TValue="string" TItem="string"
                        ValueChange="@OnSelectionChange">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>Selected: @SelectedCountry</p>

@code {
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
    
    private string SelectedCountry = "";

    private void OnSelectionChange(ChangeEventArgs<string, string> args)
    {
        SelectedCountry = args.Value;
        Console.WriteLine($"User selected: {args.Value}");
    }
}

Value Binding

Bind the selected value to a component property:

Two-Way Binding

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                @bind-Value="SelectedCountry"
                Placeholder="Select a country">
</SfAutoComplete>

<p>You selected: @SelectedCountry</p>

@code {
    private string SelectedCountry = "";
    
    private List<string> Countries = new() 
    { 
        "Austria", "Brazil", "Canada" 
    };
}

Behavior: Changing the AutoComplete updates SelectedCountry, and setting SelectedCountry in code updates the AutoComplete.

Value with Objects

For object types, the value is typically the ID or unique identifier:

<SfAutoComplete TValue="int" TItem="Employee" 
                DataSource="@Employees"
                @bind-Value="SelectedEmployeeId">
    <AutoCompleteFieldSettings Value="EmployeeId" 
                               Text="EmployeeName">
    </AutoCompleteFieldSettings>
</SfAutoComplete>

<p>Selected Employee ID: @SelectedEmployeeId</p>

@code {
    private int SelectedEmployeeId = 0;

    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
    }

    private List<Employee> Employees = new()
    {
        new Employee { EmployeeId = 1, EmployeeName = "John Smith" },
        new Employee { EmployeeId = 2, EmployeeName = "Jane Doe" }
    };
}

Combined Example

Combining grouping, sorting, multicolumn display, and selection:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="int" TItem="Employee" 
                DataSource="@Employees"
                AllowFiltering="true"
                SortOrder="SortOrder.Ascending"
                @bind-Value="SelectedEmployeeId">
    <AutoCompleteFieldSettings Value="EmployeeId" 
                               Text="EmployeeName"
                               GroupBy="Department">
    </AutoCompleteFieldSettings>
    <AutoCompleteTemplates TItem="Employee">
        <HeaderTemplate>
            <div style="display: grid; grid-template-columns: 2fr 1fr; gap: 10px; 
                        padding: 10px; background: #f5f5f5; font-weight: bold;">
                <span>Name</span>
                <span>Dept</span>
            </div>
        </HeaderTemplate>
        <ItemTemplate>
            <div style="display: grid; grid-template-columns: 2fr 1fr; gap: 10px;">
                <span>@((context as Employee)?.EmployeeName)</span>
                <span>@((context as Employee)?.Department)</span>
            </div>
        </ItemTemplate>
    </AutoCompleteTemplates>
    <AutoCompleteEvents TValue="int" TItem="Employee"
                        ValueChange="@OnSelectionChange">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>Selected ID: @SelectedEmployeeId</p>

@code {
    private int SelectedEmployeeId = 0;

    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
        public string Department { get; set; }
    }

    private List<Employee> Employees = new()
    {
        new Employee { EmployeeId = 1, EmployeeName = "Alice Brown", Department = "IT" },
        new Employee { EmployeeId = 2, EmployeeName = "Bob Johnson", Department = "IT" },
        new Employee { EmployeeId = 3, EmployeeName = "Charlie Davis", Department = "HR" },
        new Employee { EmployeeId = 4, EmployeeName = "Diana Evans", Department = "HR" }
    };

    private void OnSelectionChange(ChangeEventArgs<int, Employee> args)
    {
        Console.WriteLine($"Selected Employee ID: {args.Value}");
    }
}

Related Topics

• Data Binding
• Filtering & Search
• Templates & Styling

Filtering & Search in Syncfusion Blazor AutoComplete

Table of Contents

• Enabling Filtering
• Filter Types
• Local Data Filtering
• Remote Data Filtering
• DebounceDelay
• Minimum Character Length
• Custom Filtering
• Highlight Search Results
• Case-Sensitive Filtering

Enabling Filtering

Enable the filtering feature with the AllowFiltering property:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true"
                Placeholder="Type to search...">
</SfAutoComplete>

@code {
    private List<string> Countries = new()
    {
        "Austria",
        "Brazil",
        "Canada",
        "Denmark",
        "Egypt"
    };
}

Note: By default, AllowFiltering is false. When enabled, filtering starts immediately as users type in the search box.

Filter Types

Choose how the component compares user input to list items using FilterType:

StartsWith Filter (Default)

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true"
                FilterType="FilterType.StartsWith">
</SfAutoComplete>

Result: Typing "Br" shows "Brazil", but "azil" won't match.

Contains Filter

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true"
                FilterType="FilterType.Contains">
</SfAutoComplete>

Result: Typing "land" shows "Finland", "Ireland", "Poland".

EndsWith Filter

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true"
                FilterType="FilterType.EndsWith">
</SfAutoComplete>

Result: Typing "land" shows "Finland", "Ireland", "Poland".

Local Data Filtering

When DataSource is a local collection, filtering happens on the client side automatically:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Employee" 
                DataSource="@Employees"
                AllowFiltering="true"
                FilterType="FilterType.Contains">
    <AutoCompleteFieldSettings Value="EmployeeName" ></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Employee
    {
        public int EmployeeId { get; set; }
        public string EmployeeName { get; set; }
    }

    private List<Employee> Employees = new()
    {
        new Employee { EmployeeId = 1, EmployeeName = "John Smith" },
        new Employee { EmployeeId = 2, EmployeeName = "Jane Doe" },
        new Employee { EmployeeId = 3, EmployeeName = "Bob Johnson" }
    };
}

Typing "john" matches both "John Smith" and "Bob Johnson" with Contains filter.

Remote Data Filtering

When using remote data sources (Web API, OData), filtering requests are sent to the server:

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

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true"
                FilterType="FilterType.Contains">
    <SfDataManager Url="YOUR_API_ENDPOINT" 
                   Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor">
    </SfDataManager>
    <AutoCompleteFieldSettings Value="ProductName" >
    </AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Product
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
    }
}

Behavior: Each keystroke sends a filter request to the server with the search text. The server applies filtering and returns matching results.

DebounceDelay

Control the frequency of filtering operations with DebounceDelay (in milliseconds). This prevents excessive requests to remote servers:

Default Debounce (300ms)

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true"
                DebounceDelay="300">
    <SfDataManager Url="YOUR_API_ENDPOINT" 
                   Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor">
    </SfDataManager>
</SfAutoComplete>

Behavior: The filter request is delayed by 300ms after the user stops typing. If they continue typing, the delay resets.

Aggressive Filtering (Lower Delay)

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true"
                DebounceDelay="100">
    <SfDataManager Url="YOUR_API_ENDPOINT" 
                   Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor">
    </SfDataManager>
</SfAutoComplete>

Use When: You want near-instant feedback and can handle frequent server requests.

Disable Debounce (Real-Time Filtering)

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true"
                DebounceDelay="0">
    <SfDataManager Url="YOUR_API_ENDPOINT" 
                   Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor">
    </SfDataManager>
</SfAutoComplete>

Warning: With DebounceDelay="0", a filter request is sent for every keystroke. Use only with small datasets or high-performance backends.

Minimum Character Length

Set a minimum number of characters required before filtering starts using MinLength:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true"
                MinLength="2"
                Placeholder="Type at least 2 characters">
</SfAutoComplete>

Behavior: Typing "C" shows no results. Typing "Ca" triggers filtering and shows "Canada".

Use Case: Reduce Noise

For large datasets, require minimum input to reduce noise:

<SfAutoComplete TValue="string" TItem="Product" 
                AllowFiltering="true"
                MinLength="3"
                DebounceDelay="500">
    <SfDataManager Url="YOUR_API_ENDPOINT" 
                   Adaptor="Syncfusion.Blazor.Adaptors.ODataAdaptor">
    </SfDataManager>
</SfAutoComplete>

Effect: Reduces server load by requiring at least 3 characters before any filter request.

Custom Filtering

Implement custom filter logic using Filtering event:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="Product" 
                DataSource="@Products">
    <AutoCompleteFieldSettings Value="ProductName" ></AutoCompleteFieldSettings>
    <AutoCompleteEvents TValue="string" TItem="Product"
                        Filtering="@OnFiltering">
    </AutoCompleteEvents>
</SfAutoComplete>

@code {
    public class Product
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
        public decimal Price { get; set; }
    }

    private List<Product> Products = new()
    {
        new Product { ProductId = 1, ProductName = "Apple", Price = 50 },
        new Product { ProductId = 2, ProductName = "Apricot", Price = 40 },
        new Product { ProductId = 3, ProductName = "Banana", Price = 30 }
    };

    private void OnFiltering(FilteringEventArgs args)
    {
        // Filter only items with price > 35
        args.FilteredData = Products
            .Where(p => p.Price > 35 && p.ProductName.Contains(args.Text))
            .Cast<object>()
            .ToList();
    }
}

Advanced Example: Filter based on multiple conditions:

private void OnFiltering(FilteringEventArgs args)
{
    args.FilteredData = Products
        .Where(p => 
            p.ProductName.Contains(args.Text, StringComparison.OrdinalIgnoreCase)
            && p.Price > 25
            && p.ProductId != 999  // Exclude specific product
        )
        .Cast<object>()
        .ToList();
}

Highlight Search Results

The AutoComplete automatically highlights matching search text in results. You can customize this with CSS:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Countries"
                AllowFiltering="true"
                FilterType="FilterType.Contains">
</SfAutoComplete>

<style>
    .e-highlight {
        background-color: #fff59d;
        font-weight: bold;
    }
</style>

Result: When user types "land", the text "land" is highlighted in "Finland", "Ireland", etc.

Case-Sensitive Filtering

By default, filtering is case-insensitive. For case-sensitive filtering, use custom filtering:

@using Syncfusion.Blazor.DropDowns

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Items">
    <AutoCompleteEvents TValue="string" TItem="string"
                        Filtering="@OnCaseSensitiveFilter">
    </AutoCompleteEvents>
</SfAutoComplete>

@code {
    private List<string> Items = new() { "Apple", "apple", "APPLE" };

    private void OnCaseSensitiveFilter(FilteringEventArgs args)
    {
        // Case-sensitive filtering
        args.FilteredData = Items
            .Where(item => item.Contains(args.Text))  // Case-sensitive
            .Cast<object>()
            .ToList();
    }
}

Best Practices

1. Use DebounceDelay with Remote Data: Prevent excessive server requests 2. Set MinLength Appropriately: Balance between UX and server load 3. Choose FilterType by Use Case: StartsWith for most, Contains for flexible matching 4. Highlight Important Matches: Use custom CSS to highlight search text 5. Test Performance: Large datasets with aggressive filtering can impact performance

Related Topics

• Data Binding
• Templates & Styling
• Advanced Features

Getting Started with Syncfusion Blazor AutoComplete

Table of Contents

• Installation
• Project Setup
• Basic Implementation
• CSS & Themes
• Initial Configuration

Installation

The Syncfusion Blazor AutoComplete component is part of the DropDowns package. Install it along with the Themes package for styling.

Step 1: Install NuGet Packages

Using Visual Studio NuGet Package Manager:

Install-Package Syncfusion.Blazor.DropDowns
Install-Package Syncfusion.Blazor.Themes

Using .NET CLI:

dotnet add package Syncfusion.Blazor.DropDowns
dotnet add package Syncfusion.Blazor.Themes
dotnet restore

Step 2: Register Syncfusion Services

Register the Syncfusion Blazor service in your Program.cs:

using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");

builder.Services
    .AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) })
    .AddSyncfusionBlazor();  // Register Syncfusion services

await builder.Build().RunAsync();

Project Setup

Setup for Visual Studio

1. Create a new Blazor WebAssembly App in Visual Studio 2. Go to Tools → NuGet Package Manager → Manage NuGet Packages for Solution 3. Search for and install:

• Syncfusion.Blazor.DropDowns
• Syncfusion.Blazor.Themes

4. Register services in Program.cs (see above)

Setup for Visual Studio Code

1. Create a new Blazor WebAssembly project:

   dotnet new blazorwasm -o BlazorApp
   cd BlazorApp

2. Install packages:

   dotnet add package Syncfusion.Blazor.DropDowns
   dotnet add package Syncfusion.Blazor.Themes
   dotnet restore

3. Register services in Program.cs

Setup for .NET CLI

Create and configure a Blazor WebAssembly app:

dotnet new blazorwasm -o MyBlazorApp
cd MyBlazorApp
dotnet add package Syncfusion.Blazor.DropDowns
dotnet add package Syncfusion.Blazor.Themes
dotnet restore

CSS & Themes

Add Theme CSS

Include the Syncfusion theme CSS in your index.html (in the <head> section):

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />

Available Themes:

• bootstrap5.css - Bootstrap 5
• tailwind.css - Tailwind CSS
• fluent2.css - Microsoft Fluent 2
• material3.css - Material Design 3
• fluent.css - Microsoft Fluent
• highcontrast.css - High Contrast

Choose the theme that matches your application design.

Add Syncfusion Script

Add the Syncfusion Blazor scripts to the end of index.html (before </body>):

<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

Basic Implementation

Minimal Example with Local Data

Create a simple AutoComplete component with a list of strings:

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

<h3>AutoComplete Demo</h3>

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@CountryData" 
                Placeholder="Select a country">
</SfAutoComplete>

@code {
    private List<string> CountryData = new()
    {
        "Austria",
        "Brazil",
        "Canada",
        "Denmark",
        "Egypt",
        "Finland",
        "Germany",
        "Hungary"
    };
}

Example with Objects

For more complex scenarios, bind to objects and map fields:

@page "/autocomplete-objects"
@using Syncfusion.Blazor.DropDowns

<h3>AutoComplete with Objects</h3>

<SfAutoComplete TValue="string" TItem="Country" 
                DataSource="@Countries"
                Placeholder="Select a country">
    <AutoCompleteFieldSettings Value="CountryName"></AutoCompleteFieldSettings>
</SfAutoComplete>

@code {
    public class Country
    {
        public string CountryName { get; set; }
        public string CountryCode { get; set; }
    }

    private List<Country> Countries = new()
    {
        new Country { CountryName = "Austria", CountryCode = "AT" },
        new Country { CountryName = "Brazil", CountryCode = "BR" },
        new Country { CountryName = "Canada", CountryCode = "CA" }
    };
}

Initial Configuration

Common Initial Properties

Enable Filtering:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Items"
                AllowFiltering="true">
</SfAutoComplete>

Add Placeholder & Clear Button:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Items"
                Placeholder="Type to search..."
                ShowClearButton="true">
</SfAutoComplete>

Set Read-Only State:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Items"
                ReadOnly="true">
</SfAutoComplete>

Disable Component:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Items"
                Enabled="false">
</SfAutoComplete>

Handling Value Changes

Respond to user selections:

<SfAutoComplete TValue="string" TItem="string" 
                DataSource="@Items"
                @bind-Value="SelectedValue">
    <AutoCompleteEvents TValue="string" TItem="string"
                        ValueChange="@OnValueChange">
    </AutoCompleteEvents>
</SfAutoComplete>

<p>Selected: @SelectedValue</p>

@code {
    private string SelectedValue;
    private List<string> Items = new() { "Option1", "Option2", "Option3" };

    private void OnValueChange(ChangeEventArgs<string, string> args)
    {
        Console.WriteLine($"Selected value: {args.Value}");
    }
}

Next Steps

• Data Binding: See data-binding.md for binding local and remote data
• Filtering: See filtering-and-search.md for search and filter options
• Customization: See templates-and-styling.md for styling and templates
• Advanced: See advanced-features.md for events, virtualization, and more

Getting Started with ComboBox

This guide walks you through installing the Syncfusion Blazor ComboBox component and creating your first working example.

Installation

Step 1: Install NuGet Packages

The ComboBox component is part of the DropDowns package. Install both the component package and themes:

dotnet add package Syncfusion.Blazor.DropDowns
dotnet add package Syncfusion.Blazor.Themes

Or using Package Manager Console:

Install-Package Syncfusion.Blazor.DropDowns
Install-Package Syncfusion.Blazor.Themes

Step 2: Import Namespaces

Add the ComboBox namespace to your _Imports.razor:

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

Step 3: Register Services

In Program.cs, register the Syncfusion services:

builder.Services.AddSyncfusionBlazor();

Step 4: Add Theme Stylesheet

Add the theme CSS link in your root layout file (App.razor or _Layout.cshtml):

<!-- Choose one of these themes -->
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<!-- OR -->
<!-- <link href="_content/Syncfusion.Blazor.Themes/material.css" rel="stylesheet" /> -->
<!-- <link href="_content/Syncfusion.Blazor.Themes/fluent.css" rel="stylesheet" /> -->
<!-- <link href="_content/Syncfusion.Blazor.Themes/tailwind.css" rel="stylesheet" /> -->

Also add the Syncfusion script (usually at the end of the body):

<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

Basic Implementation

Example 1: Simple ComboBox with Local Data

@using Syncfusion.Blazor.DropDowns

<SfComboBox TItem="Country" TValue="string"
    Placeholder="Select a country"
    DataSource="@Countries">
    <ComboBoxFieldSettings Text="Name" Value="Code"></ComboBoxFieldSettings>
</SfComboBox>

@code {
    public class Country
    {
        public string Name { get; set; }
        public string Code { get; set; }
    }

    private List<Country> Countries = new()
    {
        new Country { Name = "United States", Code = "USA" },
        new Country { Name = "United Kingdom", Code = "UK" },
        new Country { Name = "Canada", Code = "CA" },
        new Country { Name = "Australia", Code = "AUS" }
    };
}

Example 2: ComboBox with Value Binding

@using Syncfusion.Blazor.DropDowns

<div class="form-group">
    <label for="country">Select Country:</label>
    <SfComboBox @ref="ComboBoxRef" 
        ID="country"
        TItem="Country" 
        TValue="string"
        Placeholder="Choose a country"
        DataSource="@Countries"
        @bind-Value="@SelectedCountry">
        <ComboBoxFieldSettings Text="Name" Value="Code"></ComboBoxFieldSettings>
    </SfComboBox>
</div>

<div style="margin-top: 20px;">
    <p><strong>Selected:</strong> @SelectedCountry</p>
</div>

@code {
    private SfComboBox<Country, string> ComboBoxRef;
    private string SelectedCountry = "USA";

    public class Country
    {
        public string Name { get; set; }
        public string Code { get; set; }
    }

    private List<Country> Countries = new()
    {
        new Country { Name = "United States", Code = "USA" },
        new Country { Name = "United Kingdom", Code = "UK" },
        new Country { Name = "Canada", Code = "CA" }
    };
}

Example 3: ComboBox with Primitive Types

When binding to simple string or integer lists:

@using Syncfusion.Blazor.DropDowns

<SfComboBox TItem="string" TValue="string"
    Placeholder="Select a fruit"
    DataSource="@Fruits"
    @bind-Value="@SelectedFruit">
</SfComboBox>

<p>Selected: @SelectedFruit</p>

@code {
    private string SelectedFruit = "Apple";
    private List<string> Fruits = new() 
    { 
        "Apple", "Banana", "Orange", "Mango" 
    };
}

Project Types

Blazor Web App (.NET 8+)

If using the new Blazor Web App template, specify the render mode:

@rendermode InteractiveServer
@* or @rendermode InteractiveWebAssembly *@
@using Syncfusion.Blazor.DropDowns

<SfComboBox TItem="Country" TValue="string"
    Placeholder="Select a country"
    DataSource="@Countries">
    <ComboBoxFieldSettings Text="Name" Value="Code"></ComboBoxFieldSettings>
</SfComboBox>

Blazor Server App

For Blazor Server, add services in Program.cs:

builder.Services.AddSyncfusionBlazor();

Blazor WebAssembly App

Ensure services are registered in Program.cs:

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.Services.AddSyncfusionBlazor();

Available Themes

Choose a theme that matches your application design:

• bootstrap5.css - Bootstrap 5 theme (default)
• material.css - Material Design theme
• material-dark.css - Material dark mode
• fluent.css - Microsoft Fluent UI
• fluent-dark.css - Fluent dark mode
• tailwind.css - Tailwind CSS theme
• fabric.css - Office Fabric theme

<!-- Example: Using Material theme -->
<link href="_content/Syncfusion.Blazor.Themes/material.css" rel="stylesheet" />

Troubleshooting Getting Started

Problem: ComboBox not rendering

• Check namespace import: @using Syncfusion.Blazor.DropDowns
• Verify theme CSS link is correct
• Ensure script link is loaded: syncfusion-blazor.min.js

Problem: Data not showing

• Verify DataSource is populated
• Check ComboBoxFieldSettings match your data properties
• For primitive types (string, int), omit the FieldSettings

Problem: Styling looks off

• Clear browser cache
• Check theme CSS matches your expectations
• Try different theme to verify it's a theme issue

Next Steps

• Data Binding: Explore different data sources (remote, complex objects, observables)
• Filtering: Enable user filtering with AllowFiltering
• Cascading: Create dependent ComboBox chains
• Templates: Customize item appearance with templates
• Validation: Integrate with EditForm for form validation

---

See also: [Data Binding](data-binding.md), [Filtering & Search](filtering.md), [Form Validation](events-and-validation.md)