ComboBox
ComboBox
ComboBox
ComboBox
Class
Definition
Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Prerelease APIs are identified by a Prerelease label.
[Contains prerelease APIs.]
Represents a selection control that combines a non-editable text box and a drop-down list box that allows users to select an item from a list.
public : class ComboBox : Selector, IComboBox, IComboBox2, IComboBox3, IComboBox4, IComboBoxOverridespublic class ComboBox : Selector, IComboBox, IComboBox2, IComboBox3, IComboBox4, IComboBoxOverridesPublic Class ComboBox Inherits Selector Implements IComboBox, IComboBox2, IComboBox3, IComboBox4, IComboBoxOverrides// This API is not available in Javascript.
<ComboBox .../>
- Inheritance
-
ComboBoxComboBoxComboBoxComboBox
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
Inherited Members
Inherited properties
Inherited events
Inherited methods
Examples
The following example demonstrates binding a ComboBox to a collection of FontFamily objects.
<ComboBox x:Name="FontsCombo" Header="Fonts" Height="44" Width="296"
ItemsSource="{x:Bind fonts}" DisplayMemberPath="Source"/>
ObservableCollection<FontFamily> fonts = new ObservableCollection<FontFamily>();
public MainPage()
{
this.InitializeComponent();
fonts.Add(new FontFamily("Arial"));
fonts.Add(new FontFamily("Courier New"));
fonts.Add(new FontFamily("Times New Roman"));
}
Remarks
ComboBox presents a drop-down list of items a user can select from.

Use a ComboBox to present a list of items that a user can select from. When the ComboBox is closed, it either displays the current selection or is empty if there is no selected item. When the ComboBox is open, it displays the list of selectable items. You can get or set the combo box's selected item by using the SelectedItem property, and get or set the index of the selected item by using the SelectedIndex property.
You populate the ComboBox by adding objects directly to the Items collection or by binding the ItemsSource property to a data source. Items added to the ComboBox are wrapped in ComboBoxItem containers.
Note
ComboBox uses a CarouselPanel as its ItemsPanel. Using a different panel as the ItemsPanel is not supported and might result in undesired behavior.
Control style and template
You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see Styling controls. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is available in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP<SDK version>\Generic folder from a Windows Software Development Kit (SDK) installation. Styles and resources from different versions of the SDK might have different values.
Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the Styling controls article.
This table shows the resources used by the ComboBox control.
| Resource key | Description |
|---|---|
| ComboBoxBackground | Background color at rest |
| ComboBoxBackgroundPointerOver | Background color on hover |
| ComboBoxBackgroundPressed | Background color when pressed |
| ComboBoxBackgroundDisabled | Background color when disabled |
| ComboBoxBackgroundUnfocused | Background color when unfocused |
| ComboBoxBackgroundBorderBrushFocused | Border color around box after item has been selected and control has focus |
| ComboBoxBackgroundBorderBrushUnfocused | Border color around box after item has been selected and control is unfocused |
| ComboBoxForeground | Text color of selected item at rest |
| ComboBoxForegroundDisabled | Text color of selected item when disabled |
| ComboBoxForegroundFocused | Text color of selected item when focused |
| ComboBoxForegroundFocusedPressed | Text color of selected item pressed and focused |
| ComboBoxPlaceHolderForeground | Placeholder text color |
| ComboBoxPlaceHolderForegroundFocusedPressed | Placeholder text color when pressed and focused |
| ComboBoxBorderBrush | Border color at rest |
| ComboBoxBorderBrushPointerOver | Border color on hover |
| ComboBoxBorderBrushPressed | Border color when pressed |
| ComboBoxBorderBrushDisabled | Border color when disabled |
| ComboBoxDropDownGlyphForeground | Drop down arrow color at rest |
| ComboBoxDropDownGlyphForegroundDisabled | Drop down arrow color when disabled |
| ComboBoxDropDownGlyphForegroundFocused | Drop down arrow color when focused |
| ComboBoxDropDownGlyphForegroundFocusedPressed | Drop down arrow color when focused and pressed |
| ComboBoxDropDownBackground | Background color of drop down arrow control bounds |
| ComboBoxDropDownForeground | Not used |
| ComboBoxDropDownBorderBrush | Border color around control's popup when selecting items |
Constructors
Properties
Header Header Header Header
Gets or sets the content for the control's header.
public : PlatForm::Object Header { get; set; }public object Header { get; set; }Public ReadWrite Property Header As object// This API is not available in Javascript.
<ComboBox Header="headerString"/>
- Value
- PlatForm::Object object object object
The content of the control's header. The default is null.
Remarks
You can set a data template for the Header by using the HeaderTemplate property.
- See Also
HeaderProperty HeaderProperty HeaderProperty HeaderProperty
Identifies the Header dependency property.
public : static DependencyProperty HeaderProperty { get; }public static DependencyProperty HeaderProperty { get; }Public Static ReadOnly Property HeaderProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the Header dependency property.
HeaderTemplate HeaderTemplate HeaderTemplate HeaderTemplate
Gets or sets the DataTemplate used to display the content of the control's header.
public : DataTemplate HeaderTemplate { get; set; }public DataTemplate HeaderTemplate { get; set; }Public ReadWrite Property HeaderTemplate As DataTemplate// This API is not available in Javascript.
<ComboBox>
<ComboBox.HeaderTemplate>
singleDataTemplate
</ComboBox.HeaderTemplate>
</ComboBox>
The template that specifies the visualization of the header object. The default is null.
- See Also
HeaderTemplateProperty HeaderTemplateProperty HeaderTemplateProperty HeaderTemplateProperty
Identifies the HeaderTemplate dependency property.
public : static DependencyProperty HeaderTemplateProperty { get; }public static DependencyProperty HeaderTemplateProperty { get; }Public Static ReadOnly Property HeaderTemplateProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the HeaderTemplate dependency property.
IsDropDownOpen IsDropDownOpen IsDropDownOpen IsDropDownOpen
Gets or sets a value that indicates whether the drop-down portion of the ComboBox is currently open.
public : PlatForm::Boolean IsDropDownOpen { get; set; }public bool IsDropDownOpen { get; set; }Public ReadWrite Property IsDropDownOpen As bool// This API is not available in Javascript.
<ComboBox IsDropDownOpen="bool"/>
- Value
- PlatForm::Boolean bool bool bool
True if the drop-down portion is open; otherwise, false. The default is false.
IsDropDownOpenProperty IsDropDownOpenProperty IsDropDownOpenProperty IsDropDownOpenProperty
Identifies the IsDropDownOpen dependency property.
public : static DependencyProperty IsDropDownOpenProperty { get; }public static DependencyProperty IsDropDownOpenProperty { get; }Public Static ReadOnly Property IsDropDownOpenProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the IsDropDownOpen dependency property.
IsEditable IsEditable IsEditable IsEditable
Gets a value that indicates whether the user can edit text in the text box portion of the ComboBox. This property always returns false.
public : PlatForm::Boolean IsEditable { get; }public bool IsEditable { get; }Public ReadOnly Property IsEditable As bool// This API is not available in Javascript.
- Value
- PlatForm::Boolean bool bool bool
False in all cases.
IsSelectionBoxHighlighted IsSelectionBoxHighlighted IsSelectionBoxHighlighted IsSelectionBoxHighlighted
Gets a value that indicates whether the SelectionBoxItem component is highlighted.
public : PlatForm::Boolean IsSelectionBoxHighlighted { get; }public bool IsSelectionBoxHighlighted { get; }Public ReadOnly Property IsSelectionBoxHighlighted As bool// This API is not available in Javascript.
- Value
- PlatForm::Boolean bool bool bool
True if the SelectionBoxItem is highlighted; otherwise, false. The default is true.
IsTextSearchEnabled IsTextSearchEnabled IsTextSearchEnabled IsTextSearchEnabled
Gets or sets a value that specifies whether a user can jump to a value by typing.
public : PlatForm::Boolean IsTextSearchEnabled { get; set; }public bool IsTextSearchEnabled { get; set; }Public ReadWrite Property IsTextSearchEnabled As bool// This API is not available in Javascript.
<ComboBox IsTextSearchEnabled="bool"/>
- Value
- PlatForm::Boolean bool bool bool
true if a user can jump to a value by typing; otherwise, false. The default is true.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
Starting in Windows 10, version 1607, ComboBox introduces a text search feature. By default, the ComboBox jumps to a relevant value as the user types. You can set the IsTextSearchEnabled property to false to disable this behavior. This is useful, for example, if you have extended ComboBox with custom text search.
Version compatibility
The IsTextSearchEnabled property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.
Note
The text search feature is available when your app is compiled for Windows 10, version 1607 and running on version 1607 (or later). It is not available when your app is compiled for a previous version or is running on a previous version.
To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.
<ComboBox x:Name="comboBox1" Loaded="ComboBox_Loaded"/>
private void ComboBox_Loaded(object sender, RoutedEventArgs e)
{
if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.ComboBox", "IsTextSearchEnabled"))
{
comboBox1.IsTextSearchEnabled = false;
}
}
IsTextSearchEnabledProperty IsTextSearchEnabledProperty IsTextSearchEnabledProperty IsTextSearchEnabledProperty
Identifies the IsTextSearchEnabled dependency property.
public : static DependencyProperty IsTextSearchEnabledProperty { get; }public static DependencyProperty IsTextSearchEnabledProperty { get; }Public Static ReadOnly Property IsTextSearchEnabledProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the IsTextSearchEnabled dependency property.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
LightDismissOverlayMode LightDismissOverlayMode LightDismissOverlayMode LightDismissOverlayMode
Gets or sets a value that specifies whether the area outside of a light-dismiss UI is darkened.
public : LightDismissOverlayMode LightDismissOverlayMode { get; set; }public LightDismissOverlayMode LightDismissOverlayMode { get; set; }Public ReadWrite Property LightDismissOverlayMode As LightDismissOverlayMode// This API is not available in Javascript.
- Value
- LightDismissOverlayMode LightDismissOverlayMode LightDismissOverlayMode LightDismissOverlayMode
A value of the enumeration that specifies whether the area outside of a light-dismiss UI is darkened. The default is Auto.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
Transient UI, such as the open drop-down of a ComboBox, closes when you click or tap outside of it. This is called light-dismiss. "Overlay" refers to the area outside of a light-dismiss UI.
By default, the "overlay" is darkened on the Xbox, and not darkened on other devices families. You can set LightDismissOverlayMode to On to make your app darken the "overlay" area on all device families, or set it to Off to not darken the "overlay" area on all device families.
Version compatibility
The LightDismissOverlayMode property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.
To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.
private void MainPage_Loaded(object sender, RoutedEventArgs e)
{
if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.ComboBox", "LightDismissOverlayMode"))
{
comboBox1.LightDismissOverlayMode = LightDismissOverlayMode.On;
}
}
LightDismissOverlayModeProperty LightDismissOverlayModeProperty LightDismissOverlayModeProperty LightDismissOverlayModeProperty
Identifies the LightDismissOverlayMode dependency property.
public : static DependencyProperty LightDismissOverlayModeProperty { get; }public static DependencyProperty LightDismissOverlayModeProperty { get; }Public Static ReadOnly Property LightDismissOverlayModeProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the LightDismissOverlayMode dependency property.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
MaxDropDownHeight MaxDropDownHeight MaxDropDownHeight MaxDropDownHeight
Gets or sets the maximum height for a combo box drop-down.
public : double MaxDropDownHeight { get; set; }public double MaxDropDownHeight { get; set; }Public ReadWrite Property MaxDropDownHeight As double// This API is not available in Javascript.
<ComboBox MaxDropDownHeight="double"/>
- Value
- double double double double
The maximum height of the drop-down. The default is infinity.
Remarks
Note
In Windows 8, this property is ignored. If this property is set incorrectly (set to 0, for example) in an app that's compiled for Windows 8, the app might behave incorrectly or crash when it's run in Windows 8.1. You should set this property to a value of 76 or greater to make sure the scroll buttons show and behave correctly when the ComboBox is open.
MaxDropDownHeightProperty MaxDropDownHeightProperty MaxDropDownHeightProperty MaxDropDownHeightProperty
Identifies the MaxDropDownHeight dependency property.
public : static DependencyProperty MaxDropDownHeightProperty { get; }public static DependencyProperty MaxDropDownHeightProperty { get; }Public Static ReadOnly Property MaxDropDownHeightProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the MaxDropDownHeight dependency property.
PlaceholderForeground PlaceholderForeground PlaceholderForeground PlaceholderForeground
Prerelease. Gets or sets a brush that describes the color of placeholder text.
public : Brush PlaceholderForeground { get; set; }public Brush PlaceholderForeground { get; set; }Public ReadWrite Property PlaceholderForeground As Brush// This API is not available in Javascript.
<ComboBox PlaceholderForeground="{StaticResource resourceName}" .../>
| Device family |
Windows 10 Insider Preview (introduced v10.0.16257.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v5)
|
PlaceholderForegroundProperty PlaceholderForegroundProperty PlaceholderForegroundProperty PlaceholderForegroundProperty
Prerelease. Identifies the PlaceholderForeground dependency property.
public : static DependencyProperty PlaceholderForegroundProperty { get; }public static DependencyProperty PlaceholderForegroundProperty { get; }Public Static ReadOnly Property PlaceholderForegroundProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the PlaceholderForeground dependency property.
| Device family |
Windows 10 Insider Preview (introduced v10.0.16257.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v5)
|
PlaceholderText PlaceholderText PlaceholderText PlaceholderText
Gets or sets the text that is displayed in the control until the value is changed by a user action or some other operation.
public : PlatForm::String PlaceholderText { get; set; }public string PlaceholderText { get; set; }Public ReadWrite Property PlaceholderText As string// This API is not available in Javascript.
<ComboBox PlaceholderText="placeholderString"/>
- Value
- PlatForm::String string string string
The text that is displayed in the control when no value is selected. The default is an empty string ("").
Examples
Here's how to add placeholder text to a ComboBox.
<ComboBox Header="Colors" PlaceholderText="Pick a color">
<x:String>Blue</x:String>
<x:String>Green</x:String>
<x:String>Red</x:String>
<x:String>Yellow</x:String>
</ComboBox>
Remarks
The placeholder text is shown when the SelectedIndex is -1 and the SelectedItem is null. (These two properties are kept in sync.) A user can't display the placeholder text once an item has been selected. However, you can programmatically set either the SelectedIndex to -1 or the SelectedItem to null to cause the placeholder text to be shown again.
PlaceholderTextProperty PlaceholderTextProperty PlaceholderTextProperty PlaceholderTextProperty
Identifies the PlaceholderText dependency property.
public : static DependencyProperty PlaceholderTextProperty { get; }public static DependencyProperty PlaceholderTextProperty { get; }Public Static ReadOnly Property PlaceholderTextProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the PlaceholderText dependency property.
SelectionBoxItem SelectionBoxItem SelectionBoxItem SelectionBoxItem
Gets the item shown when the ComboBox is closed.
public : PlatForm::Object SelectionBoxItem { get; }public object SelectionBoxItem { get; }Public ReadOnly Property SelectionBoxItem As object// This API is not available in Javascript.
- Value
- PlatForm::Object object object object
The item shown when the ComboBox is closed.
Remarks
The selection box is the text box that's shown when the ComboBox is closed.
SelectionBoxItemTemplate SelectionBoxItemTemplate SelectionBoxItemTemplate SelectionBoxItemTemplate
Gets the template applied to the selection box content.
public : DataTemplate SelectionBoxItemTemplate { get; }public DataTemplate SelectionBoxItemTemplate { get; }Public ReadOnly Property SelectionBoxItemTemplate As DataTemplate// This API is not available in Javascript.
The template applied to the selection box content.
SelectionChangedTrigger SelectionChangedTrigger SelectionChangedTrigger SelectionChangedTrigger
Gets or sets a value that indicates what action causes a SelectionChanged event to occur.
public : ComboBoxSelectionChangedTrigger SelectionChangedTrigger { get; set; }public ComboBoxSelectionChangedTrigger SelectionChangedTrigger { get; set; }Public ReadWrite Property SelectionChangedTrigger As ComboBoxSelectionChangedTrigger// This API is not available in Javascript.
- Value
- ComboBoxSelectionChangedTrigger ComboBoxSelectionChangedTrigger ComboBoxSelectionChangedTrigger ComboBoxSelectionChangedTrigger
A value of the enumeration. The default is Committed.
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
SelectionChangedTriggerProperty SelectionChangedTriggerProperty SelectionChangedTriggerProperty SelectionChangedTriggerProperty
Identifies the SelectionChangedTrigger dependency property.
public : static DependencyProperty SelectionChangedTriggerProperty { get; }public static DependencyProperty SelectionChangedTriggerProperty { get; }Public Static ReadOnly Property SelectionChangedTriggerProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the SelectionChangedTrigger dependency property.
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
TemplateSettings TemplateSettings TemplateSettings TemplateSettings
Gets an object that provides calculated values that can be referenced as TemplateBinding sources when defining templates for a ComboBox control.
public : ComboBoxTemplateSettings TemplateSettings { get; }public ComboBoxTemplateSettings TemplateSettings { get; }Public ReadOnly Property TemplateSettings As ComboBoxTemplateSettings// This API is not available in Javascript.
- Value
- ComboBoxTemplateSettings ComboBoxTemplateSettings ComboBoxTemplateSettings ComboBoxTemplateSettings
An object that provides calculated values for templates.
Methods
OnDropDownClosed(Object) OnDropDownClosed(Object) OnDropDownClosed(Object) OnDropDownClosed(Object)
Invoked when the DropDownClosed event is raised.
protected : virtual void OnDropDownClosed(PlatForm::Object e)protected virtual void OnDropDownClosed(Object e)Protected Overridable Function OnDropDownClosed(e As Object) As void// This API is not available in Javascript.
- e
- PlatForm::Object Object Object Object
Event data for the event.
OnDropDownOpened(Object) OnDropDownOpened(Object) OnDropDownOpened(Object) OnDropDownOpened(Object)
Invoked when the DropDownOpened event is raised.
protected : virtual void OnDropDownOpened(PlatForm::Object e)protected virtual void OnDropDownOpened(Object e)Protected Overridable Function OnDropDownOpened(e As Object) As void// This API is not available in Javascript.
- e
- PlatForm::Object Object Object Object
Event data for the event.
Events
DropDownClosed DropDownClosed DropDownClosed DropDownClosed
Occurs when the drop-down portion of the ComboBox closes.
public : event EventHandler DropDownClosed<object>public event EventHandler DropDownClosed<object>Public Event DropDownClosed<object>// This API is not available in Javascript.
<ComboBox DropDownClosed="eventhandler"/>
Remarks
The drop-down portion of ComboBox is implemented basically as a Popup.
DropDownOpened DropDownOpened DropDownOpened DropDownOpened
Occurs when the drop-down portion of the ComboBox opens.
public : event EventHandler DropDownOpened<object>public event EventHandler DropDownOpened<object>Public Event DropDownOpened<object>// This API is not available in Javascript.
<ComboBox DropDownOpened="eventhandler"/>