ComboBox

Quick start

Use ComboBox when you want a compact, single-selection picker that expands into an overlay list. The current implementation is text-first and works best with strings, simple objects, or explicit ComboBoxItem rows.

Minimal list

<ComboBox Width="220"
          SelectedIndex="0">
  <ComboBoxItem Text="Low" />
  <ComboBoxItem Text="Medium" />
  <ComboBoxItem Text="High" />
</ComboBox>

Explicit item rows

<ComboBox Width="220" SelectedIndex="1">
  <ComboBoxItem Text="Windowed" />
  <ComboBoxItem Text="Borderless Fullscreen" />
  <ComboBoxItem Text="Exclusive Fullscreen" />
</ComboBox>

Bind the selected item

<ComboBox Width="240"
          ItemsSource="{Binding DifficultyOptions}"
          SelectedItem="{Binding SelectedDifficulty}" />

How the current ComboBox behaves

This ComboBox is closer to a selector plus popup overlay than to WPF's full editable ComboBox surface. The closed control is owner-drawn, and the drop-down is backed by an internal ListBox hosted inside a Popup.

• The drop-down aligns to the ComboBox and uses the control width as its starting width.
• The popup is attached to the topmost ancestor panel so it renders as an overlay.
• The drop-down list uses single selection.
• Long lists scroll vertically inside the popup.

<ComboBox Width="220"
          IsDropDownOpen="{Binding IsGraphicsPickerOpen}"
          SelectedIndex="0">
  <ComboBoxItem Text="DirectX" />
  <ComboBoxItem Text="Vulkan" />
  <ComboBoxItem Text="OpenGL" />
</ComboBox>

What to put in the item list

The selected caption is generated from the underlying item value. That makes item choice important. If your items are not text-oriented, the control can only fall back to ToString().

The current display resolution rules are, in order:

• ComboBoxItem.Text when it is non-empty.
• Resolved text from a nested Label when the item content is a label.
• The item's ToString() result.

Safe pattern for explicit captions

<ComboBox Width="260" SelectedIndex="0">
  <ComboBoxItem Text="1920 x 1080" />
  <ComboBoxItem Text="2560 x 1440" />
  <ComboBoxItem Text="3840 x 2160" />
</ComboBox>

ItemsSource with simple values

<ComboBox Width="220"
          ItemsSource="{Binding LanguageCodes}"
          SelectedItem="{Binding CurrentLanguageCode}" />

Selection and events

ComboBox inherits the selector contract, so selection is driven through SelectedIndex, SelectedItem, and the bubbling SelectionChanged event.

Handle SelectionChanged in XAML

<ComboBox Width="220"
          SelectedIndex="0"
          SelectionChanged="OnQualityChanged">
  <ComboBoxItem Text="Low" />
  <ComboBoxItem Text="Medium" />
  <ComboBoxItem Text="Ultra" />
</ComboBox>

namespace InkkSlinger;

public partial class GraphicsView : UserControl
{
    public GraphicsView()
    {
        InitializeComponent();
    }

    private void OnQualityChanged(object? sender, SelectionChangedEventArgs args)
    {
        var comboBox = (ComboBox)sender!;
        var selectedQuality = comboBox.SelectedItem;
        // React to the new value here.
    }
}

• SelectedIndex defaults to -1 when nothing is selected.
• SelectedItem is the original item object, not a display string copy.
• The control is intended for single-selection workflows.

Layout and sizing

The closed ComboBox measures around the selected caption plus its chrome. The arrow area is reserved internally, and the current font size contributes directly to the desired height.

• BorderThickness is a single float value, not a per-side thickness.
• Padding is a normal Thickness and affects both measure and render placement.
• The popup width tracks the ComboBox width, with an internal minimum width floor.
• The popup height never shrinks below the control's minimum drop-down constraint.

Constrain a tall list

<ComboBox Width="260"
          MaxDropDownHeight="140"
          SelectedIndex="0">
  <ComboBoxItem Text="Autosave every 1 minute" />
  <ComboBoxItem Text="Autosave every 5 minutes" />
  <ComboBoxItem Text="Autosave every 10 minutes" />
  <ComboBoxItem Text="Autosave every 15 minutes" />
  <ComboBoxItem Text="Autosave every 30 minutes" />
  <ComboBoxItem Text="Manual only" />
</ComboBox>

Styling the control and its rows

There are two styling layers: the closed ComboBox chrome, and the generated drop-down rows. The closed control uses its own Background, Foreground, BorderBrush, BorderThickness, and Padding. Drop-down rows are generated as ComboBoxItem containers.

Style the closed control

<ComboBox Width="230"
          SelectedIndex="0"
          Background="#1A2430"
          Foreground="#F4FAFF"
          BorderBrush="#4FC7C1"
          BorderThickness="1"
          Padding="10,6">
  <ComboBoxItem Text="Balanced" />
  <ComboBoxItem Text="Performance" />
  <ComboBoxItem Text="Battery Saver" />
</ComboBox>

Style generated drop-down rows

<UserControl.Resources>
  <Style x:Key="ThemeComboRowStyle" TargetType="{x:Type ComboBoxItem}">
    <Setter Property="Foreground" Value="#EAF3FF" />
    <Setter Property="Background" Value="#13202D" />
    <Setter Property="BorderBrush" Value="#274057" />
    <Setter Property="SelectedBackground" Value="#24507A" />
    <Setter Property="Padding" Value="10,7" />
    <Style.Triggers>
      <Trigger Property="IsMouseOver" Value="True">
        <Setter Property="Background" Value="#1C3145" />
      </Trigger>
      <Trigger Property="IsSelected" Value="True">
        <Setter Property="BorderBrush" Value="#6EC7FF" />
      </Trigger>
    </Style.Triggers>
  </Style>
</UserControl.Resources>

<ComboBox Width="240"
          SelectedIndex="0"
          ItemContainerStyle="{StaticResource ThemeComboRowStyle}">
  <ComboBoxItem Text="English" />
  <ComboBoxItem Text="French" />
  <ComboBoxItem Text="Japanese" />
</ComboBox>

When ItemContainerStyle is not set, generated rows inherit typography from the ComboBox automatically. Once you set ItemContainerStyle, you should treat that style as the owner of row visuals and typography.

Property and event reference

Patterns and examples

Settings picker

<StackPanel>
  <Label Text="Texture quality" Margin="0,0,0,6" />
  <ComboBox Width="220" SelectedIndex="1">
    <ComboBoxItem Text="Low" />
    <ComboBoxItem Text="Medium" />
    <ComboBoxItem Text="High" />
  </ComboBox>
</StackPanel>

MVVM selection binding

<StackPanel>
  <Label Text="Language" Margin="0,0,0,6" />
  <ComboBox Width="220"
            ItemsSource="{Binding AvailableLanguages}"
            SelectedItem="{Binding CurrentLanguage}" />
</StackPanel>

Programmatically open the picker

<ComboBox Width="260"
          SelectedItem="{Binding ActiveProfile}"
          IsDropDownOpen="{Binding ShowProfilePicker}" />

Simple object list with useful ToString output

public sealed class ResolutionOption
{
    public ResolutionOption(int width, int height)
    {
        Width = width;
        Height = height;
    }

    public int Width { get; }
    public int Height { get; }

    public override string ToString() => $"{Width} x {Height}";
}

<ComboBox Width="220"
          ItemsSource="{Binding ResolutionOptions}"
          SelectedItem="{Binding SelectedResolution}" />

Notes and pitfalls