syncfusion-winui-combobox（Synfusion WinUI 组合框）

Implementing ComboBoxes (Syncfusion WinUI)

When to Use This Skill

Use this skill when the user needs to:

• Implement a dropdown selection control in WinUI applications
• Enable single or multiple item selection from a list
• Add filtering and searching capabilities to a dropdown
• Create an editable dropdown with auto-completion
• Display selected items as tokens or delimiter-separated values
• Group dropdown items by categories
• Customize dropdown appearance with templates
• Handle user input validation and invalid entries
• Implement keyboard navigation in dropdowns

Component Overview

The Syncfusion WinUI ComboBox (SfComboBox) is a feature-rich dropdown selection control that supports:

• Selection Modes: Single and multiple selection with checkbox support
• Filtering: Built-in filtering with StartsWith or Contains modes
• Editing: Editable and non-editable modes with auto-completion
• Display Modes: Token display or delimiter-separated display for multiple selections
• Searching: Text search with highlighting
• Grouping: Organize items into categories
• Customization: Extensive template and styling options
• Keyboard Support: Full keyboard navigation and shortcuts
• Accessibility: WCAG compliant with screen reader support

⚠️ Security Considerations

When using ComboBox with external data sources or custom filtering:

• Data Source Security: Only bind ItemsSource to trusted internal data sources. Validate any external data before displaying.
• Image Binding: Do not bind Image.Source to untrusted external URLs. Use embedded resources (ms-appx:///) or local files (file:///) instead.
• Custom Filtering: If implementing IComboBoxFilterBehavior with external APIs, always whitelist allowed domains and sanitize responses.
• User Input: In editable mode, validate and sanitize user input, especially if passed to backend services.

When to use ComboBox vs. other dropdowns:

• Use ComboBox when: You need filtering, editing, or multiple selection with tokens
• Use DropDownList when: You need simple single-selection without editing
• Use MultiSelect Dropdown when: You need multiple selection without tokens (checkbox only)
• Use AutoComplete when: You need type-ahead suggestion without dropdown list persistence

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installing NuGet package (Syncfusion.Editors.WinUI)
• Installing NuGet package (Syncfusion.Editors.WinUI)
• Note: make sure to update the Syncfusion.Editors.WinUI NuGet package to the latest available version before release.
• Basic ComboBox implementation in XAML and C#
• Populating items with SfComboBoxItem
• Data binding with ItemsSource
• Setting DisplayMemberPath and TextMemberPath
• Customizing SelectionBox UI

Selection Modes

📄 Read: references/selection.md

• Single selection (UI and programmatic)
• SelectionChangeTrigger (Committed vs Always)
• Multiple selection with checkboxes
• Delimiter display mode for multiple selections
• Token display mode with removable tokens
• Hiding/showing checkboxes
• Auto-append UI types (TextWithSelection vs Text)
• SelectionChanged and SelectionChanging events

Filtering and Searching

📄 Read: references/filtering.md

• Enabling filtering with IsFilteringEnabled
• Filter modes (StartsWith, Contains)
• TextSearchMode configuration
• Custom filtering with IComboBoxFilterBehavior
• Implementing GetMatchingIndexes for custom logic
• Filter examples and patterns

📄 Read: references/searching.md

• Text search functionality
• IsTextSearchEnabled property
• Auto-complete behavior
• Highlighting search results
• Search customization options

Editing Modes

📄 Read: references/editing.md

• Editable vs non-editable modes (IsEditable property)
• Auto-completion and text appending
• Setting null values with AllowNull
• Opening dropdown programmatically (IsDropDownOpen)
• Handling invalid input with InputSubmitted event
• Input validation patterns

Grouping and Organization

📄 Read: references/grouping.md

• Grouping items by category
• GroupMemberPath configuration
• Customizing group headers
• Group templates and styling
• Sorting within groups

UI Customization

📄 Read: references/ui-customization.md

• ItemTemplate for dropdown items
• SelectionBoxItemTemplate for selected item display
• Header and footer templates
• Styling ComboBox elements
• Theme customization
• ComboBoxTokenItem styling for token mode
• Custom template examples

Keyboard and Advanced Features

📄 Read: references/keyboard-and-advanced.md

• Keyboard navigation shortcuts
• Leading and trailing views
• Watermark/placeholder text (PlaceholderText)
• Accessibility features
• Performance optimization for large datasets
• Troubleshooting common issues

Quick Start Example

Basic Single-Selection ComboBox

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <editors:SfComboBox x:Name="comboBox"
                        Width="250"
                        PlaceholderText="Select a social media"
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name" />
</Window>

// Model
public class SocialMedia
{
    public string Name { get; set; }
    public int ID { get; set; }
}

// ViewModel
public class SocialMediaViewModel
{
    public ObservableCollection<SocialMedia> SocialMedias { get; set; }

    public SocialMediaViewModel()
    {
        SocialMedias = new ObservableCollection<SocialMedia>
        {
            new SocialMedia { Name = "Facebook", ID = 0 },
            new SocialMedia { Name = "Twitter", ID = 1 },
            new SocialMedia { Name = "Instagram", ID = 2 }
        };
    }
}

// Set DataContext
comboBox.DataContext = new SocialMediaViewModel();

Editable ComboBox with Filtering

<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="StartsWith"
                    PlaceholderText="Type to filter..."
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

Multiple Selection with Tokens

<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    IsEditable="True"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

Common Patterns

Pattern 1: Editable Dropdown with Auto-Complete

When the user types, automatically filter and suggest matching items:

<editors:SfComboBox IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="StartsWith"
                    IsTextSearchEnabled="True"
                    ItemsSource="{Binding Cities}"
                    DisplayMemberPath="CityName"
                    TextMemberPath="CityName" />

Key Configuration:

• IsEditable="True": Enables text input
• IsFilteringEnabled="True": Filters items as user types
• TextSearchMode="StartsWith": Filters items starting with entered text
• IsTextSearchEnabled="True": Auto-appends first match to typed text

Pattern 2: Multiple Selection with Custom Delimiter

Display multiple selected items separated by a custom delimiter:

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Delimiter"
                    DelimiterText=" | "
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

// Access selected items
var selectedItems = comboBox.SelectedItems;
foreach (var item in selectedItems)
{
    // Process each selected item
}

Pattern 3: Token Mode with Custom Token Template

Display selected items as removable tokens with custom styling:

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.TokenItemTemplate>
        <DataTemplate>
            <Grid Background="LightBlue"
                  Padding="8,4"
                  CornerRadius="4">
                <TextBlock Text="{Binding Name}"
                          Foreground="DarkBlue" />
            </Grid>
        </DataTemplate>
    </editors:SfComboBox.TokenItemTemplate>
</editors:SfComboBox>

Pattern 4: Handling Invalid Input

Validate and handle user input that doesn't match any items:

<editors:SfComboBox x:Name="comboBox"
                    IsEditable="True"
                    InputSubmitted="OnInputSubmitted"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

private async void OnInputSubmitted(object sender, ComboBoxInputSubmittedEventArgs e)
{
    // Option 1: Show error message
    var dialog = new ContentDialog
    {
        Content = $"'{e.Text}' is not a valid option. Please select from the list.",
        CloseButtonText = "Close"
    };
    dialog.XamlRoot = this.Content.XamlRoot;
    await dialog.ShowAsync();

    // Option 2: Add new item dynamically (for multiple selection)
    // e.Item = new YourModel { Name = e.Text, ID = comboBox.Items.Count };

    // Option 3: Prevent selection
    // e.Handled = true;
}

Pattern 5: Custom Filtering Logic

Implement custom filtering for complex scenarios:

public class CustomFilterBehavior : IComboBoxFilterBehavior
{
    public List<int> GetMatchingIndexes(SfComboBox source, ComboBoxFilterInfo filterInfo)
    {
        var filteredList = new List<int>();
        var items = source.Items.OfType<YourModel>().ToList();

        // Custom filtering logic - search in multiple properties
        filteredList.AddRange(
            from item in items
            where item.Name.Contains(filterInfo.Text, StringComparison.OrdinalIgnoreCase) ||
                  item.Category.Contains(filterInfo.Text, StringComparison.OrdinalIgnoreCase)
            select items.IndexOf(item)
        );

        return filteredList;
    }
}

<editors:SfComboBox ItemsSource="{Binding Items}"
                    IsEditable="True"
                    IsFilteringEnabled="True"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.FilterBehavior>
        <local:CustomFilterBehavior />
    </editors:SfComboBox.FilterBehavior>
</editors:SfComboBox>

Pattern 6: Programmatic Selection Management

Control selection through code for dynamic scenarios:

// Single selection
comboBox.SelectedIndex = 2;
comboBox.SelectedItem = specificItem;

// Multiple selection
comboBox.SelectedItems.Add(item1);
comboBox.SelectedItems.Add(item2);

// Clear selection
comboBox.SelectedItems.Clear();

// React to selection changes
comboBox.SelectionChanged += (sender, e) =>
{
    foreach (var added in e.AddedItems)
    {
        // Handle newly selected items
    }

    foreach (var removed in e.RemovedItems)
    {
        // Handle deselected items
    }
};

Key Properties

Data Binding

• ItemsSource: Collection of items to display (IEnumerable)
• DisplayMemberPath: Property name shown in dropdown list
• TextMemberPath: Property name shown in selection box
• SelectedItem: Currently selected item (single selection)
• SelectedItems: Collection of selected items (multiple selection)
• SelectedIndex: Index of selected item (single selection)

Selection Configuration

• SelectionMode: Single or Multiple selection
• MultiSelectionDisplayMode: Delimiter or Token for multiple selection
• DelimiterText: Character(s) separating items in delimiter mode (default: ",")
• IsMultiSelectCheckBoxEnabled: Show/hide checkboxes in dropdown (default: true)
• SelectionChangeTrigger: When to update selection - Committed or Always

Editing and Filtering

• IsEditable: Enable/disable text editing (default: false)
• IsFilteringEnabled: Enable/disable filtering (default: false)
• TextSearchMode: Filter mode - StartsWith or Contains
• IsTextSearchEnabled: Enable/disable auto-complete (default: true)
• AllowNull: Allow null selection when text is cleared (default: false)

Display and UI

• PlaceholderText: Watermark text when no selection
• IsDropDownOpen: Programmatically open/close dropdown
• SelectionBoxItemTemplate: Template for selected item display
• ItemTemplate: Template for dropdown list items
• HeaderTemplate: Template for dropdown header
• FooterTemplate: Template for dropdown footer

Grouping

• GroupMemberPath: Property name for grouping items

Common Use Cases

Use Case 1: Country/State Selection

Two-level dependent dropdowns:

<editors:SfComboBox x:Name="countryComboBox"
                    PlaceholderText="Select Country"
                    ItemsSource="{Binding Countries}"
                    SelectionChanged="OnCountryChanged"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

<editors:SfComboBox x:Name="stateComboBox"
                    PlaceholderText="Select State"
                    ItemsSource="{Binding States}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

private void OnCountryChanged(object sender, ComboBoxSelectionChangedEventArgs e)
{
    if (e.AddedItems.Count > 0)
    {
        var country = e.AddedItems[0] as Country;
        // Update states collection based on selected country
        viewModel.LoadStates(country.ID);
    }
}

Use Case 2: Tag Selection for Blog Posts

Multi-select with token display for selecting multiple tags:

<editors:SfComboBox SelectionMode="Multiple"
                    MultiSelectionDisplayMode="Token"
                    IsEditable="True"
                    PlaceholderText="Add tags..."
                    ItemsSource="{Binding AvailableTags}"
                    InputSubmitted="OnTagInputSubmitted"
                    DisplayMemberPath="TagName"
                    TextMemberPath="TagName" />

Use Case 3: Searchable Employee Directory

Editable dropdown with filtering for quick employee lookup:

⚠️ Security Note: When displaying employee photos or external images, ensure images are loaded from trusted internal sources only. Do not bind to external URLs without validation.

<editors:SfComboBox IsEditable="True"
                    IsFilteringEnabled="True"
                    TextSearchMode="Contains"
                    PlaceholderText="Search employee..."
                    ItemsSource="{Binding Employees}"
                    DisplayMemberPath="FullName"
                    TextMemberPath="FullName">
    <editors:SfComboBox.ItemTemplate>
        <DataTemplate>
            <Grid>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto" />
                    <ColumnDefinition Width="*" />
                </Grid.ColumnDefinitions>
                <!-- IMPORTANT: Only use internal/trusted image sources -->
                <Ellipse Width="32" Height="32" Margin="8">
                    <Ellipse.Fill>
                        <ImageBrush ImageSource="{Binding PhotoUrl}" />
                    </Ellipse.Fill>
                </Ellipse>
                <StackPanel Grid.Column="1" VerticalAlignment="Center">
                    <TextBlock Text="{Binding FullName}" FontWeight="SemiBold" />
                    <TextBlock Text="{Binding Department}"
                              FontSize="12"
                              Foreground="Gray" />
                </StackPanel>
            </Grid>
        </DataTemplate>
    </editors:SfComboBox.ItemTemplate>
</editors:SfComboBox>

Use Case 4: Settings Panel with Grouped Options

Group related configuration options:

<editors:SfComboBox ItemsSource="{Binding Settings}"
                    GroupMemberPath="Category"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name">
    <editors:SfComboBox.GroupStyle>
        <GroupStyle>
            <GroupStyle.HeaderTemplate>
                <DataTemplate>
                    <TextBlock Text="{Binding Key}"
                              FontWeight="Bold"
                              Foreground="DarkBlue"
                              Margin="8,4" />
                </DataTemplate>
            </GroupStyle.HeaderTemplate>
        </GroupStyle>
    </editors:SfComboBox.GroupStyle>
</editors:SfComboBox>

Best Practices

1. Always set both DisplayMemberPath and TextMemberPath when binding to complex objects
2. Use IsEditable="True" with IsFilteringEnabled="True" for better user experience with large lists
3. Handle InputSubmitted event when using editable mode to validate user input
4. Choose appropriate TextSearchMode: Use StartsWith for predictable lists, Contains for flexible searching
5. Use Token mode for multiple selection when space allows, Delimiter mode for compact display
6. Implement custom FilterBehavior for complex filtering scenarios (multiple properties, fuzzy matching)
7. Set PlaceholderText to guide users on what to select
8. Use SelectionChangeTrigger="Always" for real-time updates, Committed for better performance
9. Enable AllowNull in editable mode if null selection is valid for your use case
10. Customize ItemTemplate for rich visual representation with images, icons, or multiple text lines