ListBox

Quick start

Use ListBox when you need a vertically stacked list with built-in selection, scrolling, and item-container styling. It works with explicit ListBoxItem markup, raw object collections, and grouped or collection-view-backed sources.

Minimal single-select list

<ListBox Width="260"
         Height="180"
         SelectedIndex="0">
  <ListBoxItem>
    <Label Content="Inbox" />
  </ListBoxItem>
  <ListBoxItem>
    <Label Content="Drafts" />
  </ListBoxItem>
  <ListBoxItem>
    <Label Content="Archive" />
  </ListBoxItem>
</ListBox>

Bound object list with projected text

<ListBox Width="320"
         Height="220"
         ItemsSource="{Binding RecentProjects}"
         DisplayMemberPath="Name"
         SelectedItem="{Binding ActiveProject}"
         SelectedValuePath="Id"
         SelectedValue="{Binding ActiveProjectId}" />

Extended multi-select with scrolling

<ListBox Width="340"
         Height="220"
         SelectionMode="Extended"
         VerticalScrollBarVisibility="Auto"
         ItemsSource="{Binding CandidateFiles}" />

Items and container model

ListBox inherits from Selector, which inherits from ItemsControl. The backing items can come from Items, ItemsSource, or a grouped ICollectionView, but the interactive row contract is always a realized ListBoxItem container.

• Items and ItemsSource follow the normal ItemsControl rule: do not mix direct item mutation with an active ItemsSource.
• Raw UIElement items become the content of a generated ListBoxItem, not standalone rows outside the container model.
• When neither ItemTemplate nor ItemTemplateSelector is present, generated text rows use DisplayMemberPath and ItemStringFormat before falling back to ToString().
• Generated label rows inherit the list box typography fast-path for FontFamily, FontSize, FontWeight, and FontStyle.

Simple text rows from a bound object collection

<ListBox Width="340"
         Height="220"
         ItemsSource="{Binding Agents}"
         DisplayMemberPath="DisplayName"
         ItemStringFormat="[{0}]" />

Templated rows without losing ListBoxItem containers

<ListBox Width="360"
         Height="220"
         ItemsSource="{Binding Agents}">
  <ListBox.ItemTemplate>
    <DataTemplate>
      <Grid>
        <Grid.ColumnDefinitions>
          <ColumnDefinition Width="Auto" />
          <ColumnDefinition Width="*" />
        </Grid.ColumnDefinitions>

        <Border Width="10" Height="10" Background="#4FC7C1" Margin="0,0,10,0" />
        <StackPanel Grid.Column="1">
          <Label Content="{Binding Name}" />
          <Label Content="{Binding Status}" Opacity="0.7" />
        </StackPanel>
      </Grid>
    </DataTemplate>
  </ListBox.ItemTemplate>
</ListBox>

Selection model and data API

ListBox exposes the standard Selector properties, including SelectedIndex, SelectedItem, SelectedValue, SelectedValuePath, and the read-only SelectedItems projection. Selection changes still raise the bubbled SelectionChanged routed event.

• SelectedIndex = -1, SelectedItem = null, or SelectedValue = null clears selection.
• SelectedValue resolves through SelectedValuePath; when no path is supplied, it mirrors SelectedItem.
• SelectedItems is a read-only live projection of the current selected backing items.
• SelectedIndices remains the index-based inspection API for multi-selection scenarios.

Observe selection and selected values

listBox.SelectionChanged += (_, e) =>
{
    Logger.Write($"Primary item: {listBox.SelectedItem}");
    Logger.Write($"Selected value: {listBox.SelectedValue}");

    foreach (var item in listBox.SelectedItems)
    {
        Logger.Write($"Selected item: {item}");
    }
};

Select by projected value

listBox.SelectedValuePath = nameof(ServerEntry.Id);
listBox.SelectedValue = 42;

Pointer and keyboard behavior

Pointer selection happens against realized ListBoxItem containers, and focused list boxes participate in the shared input pipeline so keyboard navigation can change selection and viewport state without extra wiring.

• Arrow and paging commands keep the new active item fully visible when selection moves.
• Ctrl+A is available for all non-single-select modes.
• ListBoxItem raises bubbled Selected and Unselected routed events as its selection state changes.

Extended multi-select picker

<ListBox Width="360"
         Height="240"
         SelectionMode="Extended"
         ItemsSource="{Binding SearchResults}" />

Programmatic selection and reveal

listBox.SelectedIndex = 27;
listBox.ScrollIntoView(listBox.SelectedItem);

Collection views, grouping, and current item sync

ListBox works with projected collection views, including grouped views. When the bound source exposes a grouped ICollectionView and you add one or more GroupStyle entries, the presenter projects GroupItem containers instead of a flat row list.

• Current-item synchronization is meaningful only for single-select lists.
• Changing the view's current item can update SelectedItem and SelectedIndex.
• Changing the list box selection can move CurrentItem and CurrentPosition on the bound view.

Grouped list backed by a collection view

<ListBox Width="360"
         Height="260"
         ItemsSource="{Binding AgentGroups}"
         IsSynchronizedWithCurrentItem="True">
  <ListBox.GroupStyle>
    <GroupStyle />
  </ListBox.GroupStyle>
</ListBox>

Presentation, items panel, and templates

The control now exposes the broader ItemsControl presentation surface. That means you can independently control text projection, item content templates, per-item container styles, the items host panel, and the outer control template.

• ItemsPanel supplies the panel used as the items host. If you do not set it, the control uses a vertical host and switches to VirtualizingStackPanel when IsVirtualizing is enabled.
• If you set ItemsPanel yourself, that custom panel takes precedence over the built-in host selection.
• The default control template expects a ScrollViewer named PART_ScrollViewer. That part becomes the row host for scrolling, selection reveal, and viewport management.

Per-item container styling by selector

public sealed class CategoryStyleSelector : StyleSelector
{
    public override Style? SelectStyle(object? item, DependencyObject container)
    {
        if (item is AgentRow row && row.IsOnline)
        {
            return OnlineStyle;
        }

        return OfflineStyle;
    }
}

listBox.ItemContainerStyleSelector = new CategoryStyleSelector();

Custom items panel

<ListBox Width="360"
         Height="220"
         ItemsSource="{Binding Logs}">
  <ListBox.ItemsPanel>
    <ItemsPanelTemplate>
      <VirtualizingStackPanel Orientation="Vertical" />
    </ItemsPanelTemplate>
  </ListBox.ItemsPanel>
</ListBox>

Custom template that preserves the scroll host contract

<Style TargetType="{x:Type ListBox}">
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="{x:Type ListBox}">
        <ScrollViewer x:Name="PART_ScrollViewer"
                      Background="{TemplateBinding Background}"
                      BorderBrush="{TemplateBinding BorderBrush}"
                      BorderThickness="{TemplateBinding BorderThickness}"
                      HorizontalScrollBarVisibility="{TemplateBinding HorizontalScrollBarVisibility}"
                      VerticalScrollBarVisibility="{TemplateBinding VerticalScrollBarVisibility}" />
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</Style>

Scrolling, layout, and virtualization

ListBox measures and arranges its active scroll host, then keeps selection changes and explicit reveal requests aligned with the viewport. The default host is vertical and optimized for row lists, but you can replace it through ItemsPanel or the outer control template.

• IsVirtualizing="True" switches the default host to VirtualizingStackPanel.
• The clip rect matches the list box layout slot, so scrolled content remains clipped to the control bounds.
• BorderThickness is a non-negative single float value on this control, not a four-sided Thickness.

Virtualized event stream

<ListBox Width="420"
         Height="260"
         IsVirtualizing="True"
         VerticalScrollBarVisibility="Auto"
         LineScrollAmount="18"
         ItemsSource="{Binding EventLines}" />

Reveal a backing item directly

var target = viewModel.SearchResults[79];
listBox.ScrollIntoView(target);
listBox.SelectedItem = target;

Property reference

The companion row type is ListBoxItem, which exposes IsSelected, IsMouseOver, selection-aware chrome properties, and bubbled Selected / Unselected routed events.

Patterns and examples

Navigation rail

<ListBox Width="240"
         Height="260"
         SelectedIndex="0">
  <ListBoxItem>
    <Label Content="Overview" />
  </ListBoxItem>
  <ListBoxItem>
    <Label Content="Build output" />
  </ListBoxItem>
  <ListBoxItem>
    <Label Content="Diagnostics" />
  </ListBoxItem>
</ListBox>

Object picker with selected value binding

<ListBox Width="320"
         Height="220"
         ItemsSource="{Binding Servers}"
         DisplayMemberPath="DisplayName"
         SelectedValuePath="Id"
         SelectedValue="{Binding ActiveServerId}" />

Restyle rows while keeping selection on the container

<ListBox Width="340"
         Height="220"
         ItemsSource="{Binding Agents}">
  <ListBox.ItemContainerStyle>
    <Style TargetType="{x:Type ListBoxItem}">
      <Setter Property="Background" Value="#152230" />
      <Setter Property="SelectedBackground" Value="#28445F" />
      <Setter Property="BorderBrush" Value="#35516B" />
      <Setter Property="Padding" Value="12,8" />
    </Style>
  </ListBox.ItemContainerStyle>
</ListBox>

Drive a details panel from the primary selection

private void OnServerListSelectionChanged(object? sender, SelectionChangedEventArgs e)
{
    if (ServerList.SelectedItem is ServerEntry selected)
    {
        DetailHost.Content = BuildServerPanel(selected);
    }
}

Grouped operational view

<ListBox Width="380"
         Height="260"
         ItemsSource="{Binding GroupedIncidents}"
         IsSynchronizedWithCurrentItem="True">
  <ListBox.GroupStyle>
    <GroupStyle />
  </ListBox.GroupStyle>
</ListBox>

Notes and pitfalls