A drop-down list control that allows users to select an item from a list.
Namespace
Inheritance
Control → TemplatedControl → ItemsControl → SelectingItemsControl → ComboBox
Properties
Gets or sets a value indicating whether the dropdown is currently open.
Gets or sets a value indicating whether the control is editable (allows text input).
Gets or sets the maximum height for the dropdown list. Default is 200.
Gets the item to display as the control’s content. Read-only.
Gets or sets the DataTemplate used to display the selected item. This has a higher priority than ItemTemplate if set.
Gets or sets the placeholder text displayed when no item is selected.
Gets or sets the brush that renders the placeholder text.
HorizontalContentAlignment
Gets or sets the horizontal alignment of the content within the control.
Gets or sets the vertical alignment of the content within the control.
Gets or sets the text used when IsEditable is true. Supports two-way binding.
Events
Occurs after the drop-down (popup) list opens.
Occurs after the drop-down (popup) list closes.
Methods
Clears the selection (sets SelectedItem to null and SelectedIndex to -1).
Template Parts
The popup that contains the dropdown list. Required.
The text box used for editable mode.
Usage
XAML Example - Basic ComboBox
<ComboBox ItemsSource="{Binding Countries}"
SelectedItem="{Binding SelectedCountry}"
PlaceholderText="Select a country" />
XAML Example - Static Items
<ComboBox PlaceholderText="Choose an option">
<ComboBoxItem Content="Option 1" />
<ComboBoxItem Content="Option 2" />
<ComboBoxItem Content="Option 3" />
<ComboBoxItem Content="Option 4" IsEnabled="False" />
<ComboBoxItem Content="Option 5" />
</ComboBox>
XAML Example - With DataTemplate
<ComboBox ItemsSource="{Binding Users}"
SelectedItem="{Binding SelectedUser}"
MaxDropDownHeight="300">
<ComboBox.ItemTemplate>
<DataTemplate>
<StackPanel Orientation="Horizontal" Spacing="10">
<Image Source="{Binding Avatar}" Width="32" Height="32" />
<StackPanel>
<TextBlock Text="{Binding Name}" FontWeight="Bold" />
<TextBlock Text="{Binding Email}"
Foreground="Gray"
FontSize="12" />
</StackPanel>
</StackPanel>
</DataTemplate>
</ComboBox.ItemTemplate>
</ComboBox>
XAML Example - Editable ComboBox
<ComboBox IsEditable="True"
Text="{Binding SearchText}"
ItemsSource="{Binding FilteredItems}"
PlaceholderText="Type to search..." />
C# Example - Programmatic Usage
var comboBox = new ComboBox
{
ItemsSource = new List<string>
{
"Red", "Green", "Blue", "Yellow", "Orange"
},
PlaceholderText = "Select a color"
};
comboBox.SelectionChanged += (sender, e) =>
{
var selected = comboBox.SelectedItem as string;
Debug.WriteLine($"Selected: {selected}");
};
// Set selected item
comboBox.SelectedIndex = 2; // Selects "Blue"
C# Example - Complex Objects
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
var comboBox = new ComboBox
{
ItemsSource = products,
DisplayMemberBinding = new Binding("Name")
};
comboBox.SelectionChanged += (sender, e) =>
{
if (comboBox.SelectedItem is Product product)
{
Debug.WriteLine($"Selected: {product.Name} - ${product.Price}");
}
};
ViewModel Example
public class MainViewModel : ViewModelBase
{
public ObservableCollection<Category> Categories { get; }
private Category? _selectedCategory;
public Category? SelectedCategory
{
get => _selectedCategory;
set
{
this.RaiseAndSetIfChanged(ref _selectedCategory, value);
OnCategoryChanged();
}
}
public MainViewModel()
{
Categories = new ObservableCollection<Category>
{
new Category { Id = 1, Name = "Electronics" },
new Category { Id = 2, Name = "Clothing" },
new Category { Id = 3, Name = "Books" }
};
}
private void OnCategoryChanged()
{
// React to selection change
if (SelectedCategory != null)
{
LoadProductsForCategory(SelectedCategory.Id);
}
}
}
Custom Selection Display
<ComboBox ItemsSource="{Binding People}"
SelectedItem="{Binding SelectedPerson}">
<!-- Template for items in dropdown -->
<ComboBox.ItemTemplate>
<DataTemplate>
<StackPanel Orientation="Horizontal">
<TextBlock Text="{Binding Name}" />
<TextBlock Text=" - " />
<TextBlock Text="{Binding Age}" />
</StackPanel>
</DataTemplate>
</ComboBox.ItemTemplate>
<!-- Different template for selected item display -->
<ComboBox.SelectionBoxItemTemplate>
<DataTemplate>
<TextBlock Text="{Binding Name}"
FontWeight="Bold" />
</DataTemplate>
</ComboBox.SelectionBoxItemTemplate>
</ComboBox>
Keyboard Navigation
ComboBox supports standard keyboard navigation:
- F4 or Alt+Down/Up: Open/close dropdown
- Enter or Space: Open dropdown (when closed)
- Escape: Close dropdown
- Up/Down arrows: Navigate items (when closed in non-editable mode)
- Tab: Close dropdown and move focus
Handling Events
var comboBox = new ComboBox();
comboBox.DropDownOpened += (sender, e) =>
{
Debug.WriteLine("Dropdown opened");
};
comboBox.DropDownClosed += (sender, e) =>
{
Debug.WriteLine("Dropdown closed");
};
comboBox.SelectionChanged += (sender, e) =>
{
Debug.WriteLine($"Selection changed to: {comboBox.SelectedItem}");
};
Source File
ComboBox.cs:1-726
See Also