ComboBox ComboBox ComboBox Class

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.

Syntax

Declaration

public class ComboBoxpublic class ComboBoxPublic Class ComboBox
<ComboBox .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

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

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

```csharp ObservableCollection fonts = new ObservableCollection();

public MainPage() { this.InitializeComponent(); fonts.Add(new FontFamily("Arial")); fonts.Add(new FontFamily("Courier New")); fonts.Add(new FontFamily("Times New Roman")); }

```

Constructors summary

Initializes a new instance of the ComboBox class.

Properties summary

Gets or sets the content for the control's header.

Identifies the Header dependency property.

Gets or sets the DataTemplate used to display the content of the control's header.

Identifies the HeaderTemplate dependency property.

Gets or sets a value that indicates whether the drop-down portion of the ComboBox is currently open.

Identifies the IsDropDownOpen dependency property.

Gets a value that indicates whether the user can edit text in the text box portion of the ComboBox. This property always returns false.

Gets a value that indicates whether the SelectionBoxItem component is highlighted.

Gets or sets a value that specifies whether a user can jump to a value by typing.

Identifies the IsTextSearchEnabled dependency property.

Gets or sets a value that specifies whether the area outside of a light-dismiss UI is darkened.

Identifies the LightDismissOverlayMode dependency property.

Gets or sets the maximum height for a combo box drop-down.

Identifies the MaxDropDownHeight dependency property.

Gets or sets the text that is displayed in the control until the value is changed by a user action or some other operation.

Identifies the PlaceholderText dependency property.

Gets the item shown when the ComboBox is closed.

Gets the template applied to the selection box content.

Gets an object that provides calculated values that can be referenced as TemplateBinding sources when defining templates for a ComboBox control.

Events summary

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

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

Constructors

  • ComboBox()
    ComboBox()
    ComboBox()
    ComboBox()

    Initializes a new instance of the ComboBox class.

    public ComboBox()public ComboBox()Public Function ComboBox() As

Properties

  • Header
    Header
    Header
    Header

    Gets or sets the content for the control's header.

    public object Header { get; set; }public object Header { get; set; }Public ReadWrite Property Header As object
    <ComboBox Header="headerString"/>
    
    

    Property Value

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

  • 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

    Property Value

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

    Property Value

  • 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

    Property Value

  • IsDropDownOpen
    IsDropDownOpen
    IsDropDownOpen
    IsDropDownOpen

    Gets or sets a value that indicates whether the drop-down portion of the ComboBox is currently open.

    public bool IsDropDownOpen { get; set; }public bool IsDropDownOpen { get; set; }Public ReadWrite Property IsDropDownOpen As bool
    <ComboBox IsDropDownOpen="bool"/>
    

    Property Value

    • 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

    Property Value

  • 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 bool IsEditable { get; }public bool IsEditable { get; }Public ReadOnly Property IsEditable As bool

    Property Value

    • bool
      bool
      bool

      False in all cases.

  • IsSelectionBoxHighlighted
    IsSelectionBoxHighlighted
    IsSelectionBoxHighlighted
    IsSelectionBoxHighlighted

    Gets a value that indicates whether the SelectionBoxItem component is highlighted.

    public bool IsSelectionBoxHighlighted { get; }public bool IsSelectionBoxHighlighted { get; }Public ReadOnly Property IsSelectionBoxHighlighted As bool

    Property Value

    • 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 bool IsTextSearchEnabled { get; set; }public bool IsTextSearchEnabled { get; set; }Public ReadWrite Property IsTextSearchEnabled As bool
    <ComboBox IsTextSearchEnabled="bool"/>
    
    

    Property Value

    • bool
      bool
      bool

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

    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

    Property Value

  • 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

    Property Value

    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

    Property Value

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

    Property Value

    • 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

    Property Value

  • 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 string PlaceholderText { get; set; }public string PlaceholderText { get; set; }Public ReadWrite Property PlaceholderText As string
    <ComboBox PlaceholderText="placeholderString"/>
    
    

    Property Value

    • string
      string
      string

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

    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.

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

    Property Value

  • SelectionBoxItem
    SelectionBoxItem
    SelectionBoxItem
    SelectionBoxItem

    Gets the item shown when the ComboBox is closed.

    public object SelectionBoxItem { get; }public object SelectionBoxItem { get; }Public ReadOnly Property SelectionBoxItem As object

    Property Value

    • 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

    Property Value

  • 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

    Property Value

Events

  • DropDownClosed
    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"/>
    

    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 DropDownOpenedpublic event EventHandler DropDownOpenedPublic Event DropDownOpened
    <ComboBox DropDownOpened="eventhandler"/>
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll