Combo​Box Combo​Box Combo​Box 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.

Prerelease. 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
<ComboBox .../>
Inheritance
Attributes
Windows 10 requirements
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.

Open combo box

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&lt;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 keyDescription
ComboBoxBackgroundBackground color at rest
ComboBoxBackgroundPointerOverBackground color on hover
ComboBoxBackgroundPressedBackground color when pressed
ComboBoxBackgroundDisabledBackground color when disabled
ComboBoxBackgroundUnfocusedBackground color when unfocused
ComboBoxBackgroundBorderBrushFocusedBorder color around box after item has been selected and control has focus
ComboBoxBackgroundBorderBrushUnfocusedBorder color around box after item has been selected and control is unfocused
ComboBoxForegroundText color of selected item at rest
ComboBoxForegroundDisabledText color of selected item when disabled
ComboBoxForegroundFocusedText color of selected item when focused
ComboBoxForegroundFocusedPressedText color of selected item pressed and focused
ComboBoxPlaceHolderForegroundPlaceholder text color
ComboBoxPlaceHolderForegroundFocusedPressedPlaceholder text color when pressed and focused
ComboBoxBorderBrushBorder color at rest
ComboBoxBorderBrushPointerOverBorder color on hover
ComboBoxBorderBrushPressedBorder color when pressed
ComboBoxBorderBrushDisabledBorder color when disabled
ComboBoxDropDownGlyphForegroundDrop down arrow color at rest
ComboBoxDropDownGlyphForegroundDisabledDrop down arrow color when disabled
ComboBoxDropDownGlyphForegroundFocusedDrop down arrow color when focused
ComboBoxDropDownGlyphForegroundFocusedPressedDrop down arrow color when focused and pressed
ComboBoxDropDownBackgroundBackground color of drop down arrow control bounds
ComboBoxDropDownForegroundNot used
ComboBoxDropDownBorderBrushBorder color around control's popup when selecting items

Constructors

ComboBox() ComboBox() ComboBox()

Properties

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
<ComboBox Header="headerString"/>

Value
PlatForm::Object object object

The content of the control's header. The default is null.

Attributes

Remarks

You can set a data template for the Header by using the HeaderTemplate property.

See Also

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

The identifier for the Header dependency property.

Attributes

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
<ComboBox>
  <ComboBox.HeaderTemplate>
    singleDataTemplate
  </ComboBox.HeaderTemplate>
</ComboBox>
Value
DataTemplate DataTemplate DataTemplate

The template that specifies the visualization of the header object. The default is null.

Attributes
See Also

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

The identifier for the HeaderTemplate dependency property.

Attributes

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
<ComboBox IsDropDownOpen="bool"/>
Value
PlatForm::Boolean bool bool

True if the drop-down portion is open; otherwise, false. The default is false.

Attributes

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

The identifier for the IsDropDownOpen dependency property.

Attributes

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
Value
PlatForm::Boolean bool bool

False in all cases.

Attributes

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
Value
PlatForm::Boolean bool bool

True if the SelectionBoxItem is highlighted; otherwise, false. The default is true.

Attributes

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
<ComboBox IsTextSearchEnabled="bool"/>

Value
PlatForm::Boolean bool bool

true if a user can jump to a value by typing; otherwise, false. The default is true.

Attributes
Additional features and requirements
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

Identifies the IsTextSearchEnabled dependency property.

public : static DependencyProperty IsTextSearchEnabledProperty { get; }public static DependencyProperty IsTextSearchEnabledProperty { get; }Public Static ReadOnly Property IsTextSearchEnabledProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsTextSearchEnabled dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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

Attributes
Additional features and requirements
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

Identifies the LightDismissOverlayMode dependency property.

public : static DependencyProperty LightDismissOverlayModeProperty { get; }public static DependencyProperty LightDismissOverlayModeProperty { get; }Public Static ReadOnly Property LightDismissOverlayModeProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the LightDismissOverlayMode dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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
<ComboBox MaxDropDownHeight="double"/>
Value
double double double

The maximum height of the drop-down. The default is infinity.

Attributes

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

Identifies the MaxDropDownHeight dependency property.

public : static DependencyProperty MaxDropDownHeightProperty { get; }public static DependencyProperty MaxDropDownHeightProperty { get; }Public Static ReadOnly Property MaxDropDownHeightProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the MaxDropDownHeight dependency property.

Attributes

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
<ComboBox PlaceholderForeground="{StaticResource resourceName}" .../>

Value
Brush Brush Brush

The brush that describes the color of placeholder text.

Attributes
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16225.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

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

The identifier for the PlaceholderForeground dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16225.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

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
<ComboBox PlaceholderText="placeholderString"/>

Value
PlatForm::String string string

The text that is displayed in the control when no value is selected. The default is an empty string ("").

Attributes

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

Identifies the PlaceholderText dependency property.

public : static DependencyProperty PlaceholderTextProperty { get; }public static DependencyProperty PlaceholderTextProperty { get; }Public Static ReadOnly Property PlaceholderTextProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the PlaceholderText dependency property.

Attributes

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
Value
PlatForm::Object object object

The item shown when the ComboBox is closed.

Attributes

Remarks

The selection box is the text box that's shown when the ComboBox is closed.

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

The template applied to the selection box content.

Attributes

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

A value of the enumeration. The default is Committed.

Attributes
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

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

The identifier for the SelectionChangedTrigger dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

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

An object that provides calculated values for templates.

Attributes

Methods

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
Parameters
e
PlatForm::Object Object Object

Event data for the event.

Attributes

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
Parameters
e
PlatForm::Object Object Object

Event data for the event.

Attributes

Events

DropDownClosed DropDownClosed DropDownClosed

Occurs when the drop-down portion of the ComboBox closes.

public : event EventHandler DropDownClosedpublic event EventHandler DropDownClosedPublic Event DropDownClosed
<ComboBox DropDownClosed="eventhandler"/>
Attributes

Remarks

The drop-down portion of ComboBox is implemented basically as a Popup.

DropDownOpened DropDownOpened DropDownOpened

Occurs when the drop-down portion of the ComboBox opens.

public : event EventHandler DropDownOpenedpublic event EventHandler DropDownOpenedPublic Event DropDownOpened
<ComboBox DropDownOpened="eventhandler"/>
Attributes

See Also