Class SfComboBox
Represents a SfComboBox control that is used to type a value or select an item from a list of predefined options. It offers many additional features, such as multiple selection with checkboxes, filtering, selection box customization and drop-down item customization.
Inherited Members
Namespace: Syncfusion.UI.Xaml.Editors
Assembly: Syncfusion.Editors.WinUI.dll
Syntax
public class SfComboBox : DropDownListBase
Remarks
Use an ComboBox control to select single or multiple items from the drop-down list. It has many features, such as multiple selection with checkboxes, editing, searching, filtering, UI customization, and custom templates.
Selection mode
The ComboBox control allows you to select single or multiple items from the drop-down list. The selection mode can be set by using the SelectionMode property. The available selection modes are,
Single: Select a single item from the drop-down list.
Multiple: Select more than one item from a drop-down list.The selected items can be displayed as tokens or simply divide them with a delimiter text in selection area.
For more info, regarding selection mode see Selection documentation
Filtering
The ComboBox control comes with a predefined set of filtering modes that filter suggestions based on the characters typed in the text box. The available filtering modes are:
Start with: Filters the suggestions when the beginning of the string has matches in the list.
Contains: Filters all the suggestion words that contain the character typed in the text box.
You can also apply your own custom filter logic to have items suggested based on your filter criteria using FilterBehavior property.
For more info, design guidance, and code examples, see Custom filtering documentation
Note: Filtering is not supported in editable mode of SfComboBox control when ItemsSource
is CollectionViewSource
.
Searching
The ComboBox control highlights the first item that fits the user input in the suggestion list. It also provides support to apply your own custom search logic to highlight item in the suggestion list based on your search criteria using SearchBehavior property.
For more info, design guidance, and code examples, see Custom searching documentation
InputSubmitted
The InputSubmitted event is triggered, when entered text is submitted that does not correspond to an item in the drop-down list. By using the Item property of ComboBoxInputSubmittedEventArgs user can add the item to the selected item(s) or set to the selected item that is assigned. If no item is assigned, then in single selection, entered text gets assigned to the selected item. In multiple selection, no text will be added to the selected items.
<editors:SfComboBox IsEditable="true"
ItemsSource="{Binding Sports}"
TextMemberPath="Name"
DisplayMemberPath="Name"
InputSubmitted="OnInputSubmitted">
</editors:SfComboBox>
private void OnInputSubmitted(object sender, ComboBoxInputSubmittedEventArgs e)
{
e.Item = new Sport() { Name = e.Text};
}
UI Customization
Selection box UI: Customize the appearance of the selection box in ComboBox control.
Drop down height: Adjust the drop-down height based on the number of items to enhance readability without scrolling.
Conditional Styling: Customize the appearance of drop-down list items conditionally based on the data.
Drop down item customization: Drop down list items can be customized with an image or custom control.
Token item customization: Token items can be customized with an image or custom control.
For more info, design guidance, and code examples, see UI Customization
Examples
For more info, design guidance, and code examples, see ComboBox documentation
Get the demos and source code from below link.
Syncfusion Controls Gallery app
View source code of demos in GitHub
The following example demonstrates, how to initialize the SfComboBox control and populate items using SfComboBoxItem.
<editors:SfComboBox>
<editors:SfComboBoxItem Content="Cricket"/>
<editors:SfComboBoxItem Content="Football" />
<editors:SfComboBoxItem Content="Golf" />
<editors:SfComboBoxItem Content="Hockey" />
</editors:SfComboBox>
The following example demonstrates, populating items using ItemsSource.
<Grid>
<Grid.DataContext>
<local:ComboBoxViewModel/>
</Grid.DataContext>
<editors:SfComboBox
ItemsSource="{Binding Sports}"
TextMemberPath="Name"
DisplayMemberPath="Name"/>
</Grid>
Constructors
SfComboBox()
Initializes a new instance of the SfComboBox class.
Declaration
public SfComboBox()
Fields
AutoAppendTypeProperty
Identifies AutoAppendType dependency property.
Declaration
public static readonly DependencyProperty AutoAppendTypeProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the AutoAppendType dependency property. |
DelimiterTextProperty
Identifies DelimiterText dependency property.
Declaration
public static readonly DependencyProperty DelimiterTextProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the DelimiterText dependency property. |
FilterBehaviorProperty
Identifies FilterBehavior dependency property.
Declaration
public static readonly DependencyProperty FilterBehaviorProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the FilterBehavior dependency property. |
IsEditableProperty
Identifies IsEditable dependency property.
Declaration
public static readonly DependencyProperty IsEditableProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the IsEditable dependency property. |
IsFilteringEnabledProperty
Identifies IsFilteringEnabled dependency property.
Declaration
public static readonly DependencyProperty IsFilteringEnabledProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the IsFilteringEnabled dependency property. |
IsMultiSelectCheckBoxEnabledProperty
Identifies IsMultiSelectCheckBoxEnabled dependency property.
Declaration
public static readonly DependencyProperty IsMultiSelectCheckBoxEnabledProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the IsMultiSelectCheckBoxEnabled dependency property. |
IsTextSearchEnabledProperty
Identifies IsTextSearchEnabled dependency property.
Declaration
public static readonly DependencyProperty IsTextSearchEnabledProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the IsTextSearchEnabled dependency property. |
ItemContainerStyleProperty
Identifies ItemContainerStyle dependency property.
Declaration
public static readonly DependencyProperty ItemContainerStyleProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the ItemContainerStyle dependency property. |
ItemContainerStyleSelectorProperty
Identifies ItemContainerStyleSelector dependency property.
Declaration
public static readonly DependencyProperty ItemContainerStyleSelectorProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the ItemContainerStyleSelector dependency property. |
MultiSelectionDisplayModeProperty
Identifies MultiSelectionDisplayMode dependency property.
Declaration
public static readonly DependencyProperty MultiSelectionDisplayModeProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the MultiSelectionDisplayMode dependency property. |
SearchBehaviorProperty
Identifies SearchBehavior dependency property.
Declaration
public static readonly DependencyProperty SearchBehaviorProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the SearchBehavior dependency property. |
SelectedIndexProperty
Identifies SelectedIndex dependency property.
Declaration
public static readonly DependencyProperty SelectedIndexProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the SelectedIndex dependency property. |
SelectionBoxItemTemplateProperty
Identifies SelectionBoxItemTemplate dependency property.
Declaration
public static readonly DependencyProperty SelectionBoxItemTemplateProperty
Field Value
Type |
---|
Microsoft.UI.Xaml.DependencyProperty |
SelectionChangeTriggerProperty
Identifies SelectionChangeTrigger dependency property.
Declaration
public static readonly DependencyProperty SelectionChangeTriggerProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the SelectionChangeTrigger dependency property. |
SelectionModeProperty
Identifies SelectionMode dependency property.
Declaration
public static readonly DependencyProperty SelectionModeProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the SelectionMode dependency property. |
TextHighlightModeProperty
Identifies TextHighlightMode dependency property.
Declaration
public static readonly DependencyProperty TextHighlightModeProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the TextHighlightMode dependency property. |
TextSearchModeProperty
Identifies TextSearchMode dependency property.
Declaration
public static readonly DependencyProperty TextSearchModeProperty
Field Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DependencyProperty | The identifier for the TextSearchMode dependency property. |
Properties
AutoAppendType
Gets or sets a auto append type.
Declaration
public ComboBoxAutoAppendType AutoAppendType { get; set; }
Property Value
Type | Description |
---|---|
ComboBoxAutoAppendType | The default value is |
DelimiterText
Gets or sets a string as delimiter which is displayed between the selected items in multiple selection mode.
Declaration
public string DelimiterText { get; set; }
Property Value
Type | Description |
---|---|
System.String | The optimal value for Delimiter is any single character. The default value is |
Remarks
This will be effective only for multiple selection mode.
The DelimiterText
will appear between two selected items to separate them.
FilterBehavior
Gets or sets the filter behavior for ComboBox control by defining the suggestions to be shown in drop down.
Declaration
public IComboBoxFilterBehavior FilterBehavior { get; set; }
Property Value
Type | Description |
---|---|
IComboBoxFilterBehavior | The default value is |
Remarks
This property has effect only in editable mode and IsFiltering property is true.
Examples
This example demonstrates how to display the cities in drop-down based on the country name entered in the ComboBox control.
<editors:SfComboBox TextMemberPath="CityName"
DisplayMemberPath="CityName"
IsEditable="True"
IsFilteringEnabled="True"
ItemsSource="{Binding Cities}">
<editors:SfComboBox.DataContext>
<local:CityViewModel/>
</editors:SfComboBox.DataContext>
<editors:SfComboBox.FilterBehavior>
<local:CityFilteringBehavior/>
</editors:SfComboBox.FilterBehavior>
</editors:SfComboBox>
IsEditable
Gets or sets a value that indicates whether the user can edit text in the text box portion of the SfComboBox.
Declaration
public bool IsEditable { get; set; }
Property Value
Type | Description |
---|---|
System.Boolean | The default value is |
Remarks
This property does not have effect when ComboBoxSelectionMode is Multiple
.
true if the user can edit text in the SfComboBox, otherwise false.
IsFilteringEnabled
Gets or sets a value indicating whether to show only filtered items based on TextSearchMode property.
Declaration
public bool IsFilteringEnabled { get; set; }
Property Value
Type | Description |
---|---|
System.Boolean | The default value is |
Remarks
This property has effect only in editable mode.
Filtering is not supported when ItemsSource
is CollectionViewSource
.
IsMultiSelectCheckBoxEnabled
Gets or sets a value indicating whether to show or hide the check box in multi-selection mode.
Declaration
public bool IsMultiSelectCheckBoxEnabled { get; set; }
Property Value
Type | Description |
---|---|
System.Boolean | The default value is |
Remarks
This will be effective only for multiple selection mode.
IsTextSearchEnabled
Gets or sets a value indicating whether a user can jump to a value by typing.
Declaration
public bool IsTextSearchEnabled { get; set; }
Property Value
Type | Description |
---|---|
System.Boolean | The default value is |
ItemContainerStyle
Gets or sets the Microsoft.UI.Xaml.Style that is applied to the generated item in drop down.
Declaration
public Style ItemContainerStyle { get; set; }
Property Value
Type | Description |
---|---|
Microsoft.UI.Xaml.Style | The default value is |
Examples
The following example shows how to define a ItemContainerStyle
for the control's items.
<editors:SfComboBox
ItemsSource="{Binding Countries}"
DisplayMemberPath="Name"
TextMemberPath="Name">
<editors:SfComboBox.ItemContainerStyle>
<Style TargetType="editors:SfComboBoxItem">
<Setter Property="Foreground" Value="Red"/>
</Style>
</editors:SfComboBox.ItemContainerStyle>
</editors:SfComboBox>
ItemContainerStyleSelector
Gets or sets a reference to a custom Microsoft.UI.Xaml.Controls.StyleSelector logic class. The StyleSelector
returns different Style values to use for the item container based on characteristics
of the object being displayed.
Declaration
public StyleSelector ItemContainerStyleSelector { get; set; }
Property Value
Type | Description |
---|---|
Microsoft.UI.Xaml.Controls.StyleSelector | A custom |
Examples
The following example shows how to define a ItemContainerStyleSelector
for the SfComboBox control.
<Application.Resources>
<Style x:Key="CountryStyle1" TargetType="editors:SfComboBoxItem">
<Setter Property="Foreground" Value="Yellow"/>
<Setter Property="Background" Value="Green"/>
<Setter Property="Content" Value="{Binding}"/>
</Style>
<Style x:Key="CountryStyle2" TargetType="editors:SfComboBoxItem">
<Setter Property="Foreground" Value="Green"/>
<Setter Property="Background" Value="Red"/>
<Setter Property="Content" Value="{Binding}"/>
</Style>
</Application.Resources>
<Grid>
<Grid.Resources>
<local:CountryStyleSelector x:Key="countryStyleSelector" />
</Grid.Resources>
<editors:SfComboBox
DisplayMemberPath="Name"
ItemsSource="{Binding Countries}"
ItemContainerStyleSelector="{StaticResource countryStyleSelector}"/> />
</Grid>
Items
Gets the collection used to generate the content of the control.
Declaration
public IList<object> Items { get; }
Property Value
Type | Description |
---|---|
System.Collections.Generic.IList<System.Object> | The default is an empty collection. |
Examples
The following example shows how to define a Items
in SfComboBox.
<editors:SfComboBox>
<editors:SfComboBoxItem Content="Cricket"/>
<editors:SfComboBoxItem Content="Football" />
<editors:SfComboBoxItem Content="Golf" />
<editors:SfComboBoxItem Content="Hockey" />
</editors:SfComboBox>
MultiSelectionDisplayMode
Gets or sets the multi selection mode for the SfComboBox control.
Declaration
public ComboBoxMultiSelectionDisplayMode MultiSelectionDisplayMode { get; set; }
Property Value
Type | Description | ||||||
---|---|---|---|---|---|---|---|
ComboBoxMultiSelectionDisplayMode | A value that indicates to perform multiple selection using Text or Tokens in SfComboBox control. The default value is Delimiter. Fields:
|
SearchBehavior
Gets or sets the search behavior for ComboBox control which defines the highlighted index based on filterted items.
Declaration
public IComboBoxSearchBehavior SearchBehavior { get; set; }
Property Value
Type | Description |
---|---|
IComboBoxSearchBehavior | The default value is |
Remarks
This property has effect only when IsTextSearchEnabled property is true.
Examples
The following example demonstrates how to highlight the first item that fully matches the typed length entered in the ComboBox control.
<editors:SfComboBox ItemsSource="{Binding Countries}"
TextMemberPath="Name"
DisplayMemberPath="Name"
IsEditable="True"
IsFilteringEnabled="True">
<editors:SfComboBox.SearchBehavior>
<local:StringLengthSearchingBehavior/>
</editors:SfComboBox.SearchBehavior>
</editors:SfComboBox>
SelectedIndex
Gets or sets the index of the selected item.
Declaration
public int SelectedIndex { get; set; }
Property Value
Type | Description |
---|---|
System.Int32 | The index of the selected item. The default value is |
Remarks
This property does not have effect in multiple selection mode.
SelectionBoxItemTemplate
Gets or sets the DataTemplate
that is used to display the content of SfComboBox.
Declaration
public DataTemplate SelectionBoxItemTemplate { get; set; }
Property Value
Type | Description |
---|---|
Microsoft.UI.Xaml.DataTemplate | The default value of |
Remarks
This property does not have effect when editable mode is enabled.
Examples
The following example shows how to define a SelectionBoxItemTemplate
for the SfComboBox control.
<Grid>
<Grid.DataContext>
<local:ComboBoxViewModel/>
</Grid.DataContext>
<editors:SfComboBox
x:Name="comboBox"
ItemsSource="{Binding Countries}"
TextMemberPath="Name"
DisplayMemberPath="Name">
<editors:SfComboBox.SelectionBoxItemTemplate>
<DataTemplate>
<TextBlock
DataContext="{Binding ElementName=comboBox, Path=SelectedItem}"
Margin="12,5,0,6"
Text="{Binding Name}"
Foreground="Red"
FontWeight="Bold"/>
</DataTemplate>
</editors:SfComboBox.SelectionBoxItemTemplate>
</editors:SfComboBox>
</Grid>
SelectionChangeTrigger
Gets or sets a value that indicates what action causes a SelectionChanged event to occur.
Declaration
public ComboBoxSelectionChangeTrigger SelectionChangeTrigger { get; set; }
Property Value
Type | Description | ||||||
---|---|---|---|---|---|---|---|
ComboBoxSelectionChangeTrigger | A value that indicates what action causes a SelectionChanged event to occur in ComboBox control. The default value is Committed. Fields:
|
Remarks
This property has effect only in single selection mode.
SelectionMode
Gets or sets the selection behavior for the SfComboBox control.
Declaration
public ComboBoxSelectionMode SelectionMode { get; set; }
Property Value
Type | Description | ||||||
---|---|---|---|---|---|---|---|
ComboBoxSelectionMode | A value that indicates the selection behavior for a ComboBox control. The default value is Single. Fields:
|
Remarks
Allows to select either a single item or multiple items.
TextHighlightMode
Gets or sets a text highlighting mode.
Declaration
public ComboBoxTextHighlightMode TextHighlightMode { get; set; }
Property Value
Type | Description |
---|---|
ComboBoxTextHighlightMode | The default value is |
TextSearchMode
Gets or sets the TextSearchMode
to search the item which matches the search text with the beginning of the texts or contains the search text in the list.
Declaration
public ComboBoxTextSearchMode TextSearchMode { get; set; }
Property Value
Type | Description | ||||||
---|---|---|---|---|---|---|---|
ComboBoxTextSearchMode | A value that indicates the text search behavior for a ComboBox control. The default value is StartsWith. Fields:
|
Methods
Dispose()
Dispose the Control from the memory.
Declaration
public override void Dispose()
Overrides
OnApplyTemplate()
Declaration
protected override void OnApplyTemplate()
Overrides
OnCreateAutomationPeer()
Declaration
protected override AutomationPeer OnCreateAutomationPeer()
Returns
Type |
---|
Microsoft.UI.Xaml.Automation.Peers.AutomationPeer |
OnGotFocus(RoutedEventArgs)
Declaration
protected override void OnGotFocus(RoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.RoutedEventArgs | e |
Overrides
OnLostFocus(RoutedEventArgs)
Declaration
protected override void OnLostFocus(RoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.RoutedEventArgs | e |
Overrides
OnPointerEntered(PointerRoutedEventArgs)
Declaration
protected override void OnPointerEntered(PointerRoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.Input.PointerRoutedEventArgs | e |
Overrides
OnPointerExited(PointerRoutedEventArgs)
Declaration
protected override void OnPointerExited(PointerRoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.Input.PointerRoutedEventArgs | e |
Overrides
OnPointerPressed(PointerRoutedEventArgs)
Declaration
protected override void OnPointerPressed(PointerRoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.Input.PointerRoutedEventArgs | e |
OnPointerReleased(PointerRoutedEventArgs)
Declaration
protected override void OnPointerReleased(PointerRoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.Input.PointerRoutedEventArgs | e |
OnPointerWheelChanged(PointerRoutedEventArgs)
Declaration
protected override void OnPointerWheelChanged(PointerRoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.Input.PointerRoutedEventArgs | e |
OnPreviewKeyDown(KeyRoutedEventArgs)
Declaration
protected override void OnPreviewKeyDown(KeyRoutedEventArgs e)
Parameters
Type | Name | Description |
---|---|---|
Microsoft.UI.Xaml.Input.KeyRoutedEventArgs | e |
Events
InputSubmitted
Occurs when the user submits some text that does not correspond to an item in the ComboBox dropdown list.
Declaration
public event EventHandler<ComboBoxInputSubmittedEventArgs> InputSubmitted
Event Type
Type |
---|
System.EventHandler<ComboBoxInputSubmittedEventArgs> |
Examples
This example demonstrates how to invoke InputSubmitted event.
<editors:SfComboBox
x:Name="comboBox"
IsEditable="true"
ItemsSource="{Binding Countries}"
TextMemberPath="Name"
DisplayMemberPath="Name"
InputSubmitted="OnEditingComboBoxInputSubmitted" />
SelectionChanged
Occurs when the SelectedItem
or SelectedItems
is changed.
Declaration
public event EventHandler<ComboBoxSelectionChangedEventArgs> SelectionChanged
Event Type
Type |
---|
System.EventHandler<ComboBoxSelectionChangedEventArgs> |
Examples
This example demonstrates how to invoke SelectionChanged event.