Untitled

The ListBox is an ItemsControl which displays items in a multi-line list box and allows individual selection.

The items to display in the ListBox are specified using the Items property. This property will often be bound to a collection on the control's DataContext:

<ListBox Items="{Binding MyItems}"/>

Customizing the item display

You can customize how an item is displayed by specifying an ItemTemplate. For example to display each item inside a red border with rounded corners:

<ListBox Items="{Binding MyItems}">
    <ListBox.ItemTemplate>
        <DataTemplate>
            <Border Background="Red" CornerRadius="4" Padding="4">
                <TextBlock Text="{Binding}"/>
            </Border>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>

Containers

Each item displayed in a ListBox will be wrapped in a ListBoxItem - this is called the container. The container hosts the content specified in the ItemTemplate but it is not part of the ItemTemplate itself. It is the container that contains the logic for displaying selected items.

Sometimes you will want to customize the container itself. You can do this by including a style targeting ListBoxItem in the ListBox:

<ListBox Items="{Binding Items}">
    <ListBox.Styles>
        <!-- Give the ListBoxItems a fixed with of 100 and right-align them -->
        <Style Selector="ListBoxItem">
            <Setter Property="Width" Value="100"/>
            <Setter Property="HorizontalAlignment" Value="Right"/>
        </Style>
    </ListBox.Styles>
<ListBox>

Selection

There are several properties related to selection on ListBox:

SelectionMode

Controls the type of selection that can be made on the ListBox:

These values can be combined, e.g.:

<ListBox SelectionMode="Multiple,Toggle">

SelectedIndex

Exposes the index of the selected item, or in the case of multiple selection the first selected item. You will often want to bind this to a view model if your list SelectionMode is set to Single.

<ListBox SelectedIndex="{Binding SelectedIndex}">

public MyViewModel : ReactiveObject
{
    int selectedIndex;

    public int SelectedIndex
    {
        get => selectedIndex;
        set => this.RaiseAndSetIfChanged(ref selectedIndex, value);
    }
}

By default bindings to this property are two-way.

SelectedItem

Exposes the selected item in the Items collection, or in the case of multiple selection the first selected item. You will often want to bind this to a view model if your list SelectionMode is set to Single.

<ListBox SelectedItem="{Binding SelectedItem}">

public MyViewModel : ReactiveObject
{
    MyItem selectedItem;

    public MyItem SelectedItem
    {
        get => selectedItem;
        set => this.RaiseAndSetIfChanged(ref selectedItem, value);
    }
}

By default bindings to this property are two-way.

Selection

The Selection property exposes an ISelectionModel object with various methods to track multiple selected items. You can create a SelectionModel object in your view model and bind it to this property and subsequently control the selection from your view model.

SelectionModel also exposes batching functionality through its Update() method and a SelectionChanged event which details exactly which items have been selected and deselected.

<ListBox Items="{Binding Items}" Selection="{Binding Selection}">

public class MyViewModel
{
    public MyViewModel()
    {
        Items = CreateItems();

        // SelectionModel.Source can be set to Items here, or if it is left null it will be set by
        // the `ListBox` when bound.
        Selection = new SelectionModel());
        Selection.SelectionChanged += SelectionChanged;

        // Select item 10 in Items.
        Selection.Select(10);
    }

    public ObservableCollection<MyItem> Items { get; }
    public SelectionModel Selection { get; }

    // A method bound to e.g. a button which will select the first 100 items.
    public void SelectFirst100() => Selection.SelectRange(0, 99);

    // Switch to single selection via the view model.
    public void SwitchToSingleSelect() => Selection.SingleSelect = true;

    void SelectionChanged(object sender, SelectionModelSelectionChangedEventArgs e)
    {
        // ... handle selection changed
    }
}

By default bindings to this property are one-way.

SelectedItems

This property holds the selected items in an IList. It can be bound to any list that implements IList but it will usually be bound to a collection which also implements INotifyCollectionChanged such as ObservableCollection<>.

<ListBox SelectedItems="{Binding SelectedItems}">

public MyViewModel : ReactiveObject
{
    public ObservableCollection<MyItem> SelectedItems { get; } = new ObservableCollection<MyItem>();
}

Preventing Horizontal Scrolling

By default if an item is too wide to display in the ListBox, a horizontal scrollbar will be displayed. If instead you want items to be constrained to the width of the ListBox (for example if you want wrapping text in the items) you can disable the horizontal scrollbar by setting ScrollViewer.HorizontalScrollBarVisibility="Disabled".

<ListBox Items="{Binding MyItems}" Width="250" ScrollViewer.HorizontalScrollBarVisibility="Disabled">
    <ListBox.ItemTemplate>
        <DataTemplate>
            <Border Background="Red" CornerRadius="4" Padding="4">
                <TextBlock Text="{Binding}" TextWrapping="Wrap"/>
            </Border>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>

Source code

ListBox.cs