listbox.md

-api-id	-api-type
T:Windows.UI.Xaml.Controls.ListBox	winrt class

Windows.UI.Xaml.Controls.ListBox

-description

Presents a list of items the user can select from.

-xaml-syntax

<ListBox .../>
-or-
<ListBox ...>
  oneOrMoreItems
</ListBox>

-remarks

Tip

For more info, design guidance, and code examples, see Lists.

ListBox lets users select from a pre-defined list of options presented like a text control. Use a ListBox when you want the options to be visible all the time or when users can select more than one option at a time. ListBox controls are always open, so several items can be displayed without user interaction.

Note

ListBox is useful when you are upgrading a Universal Windows 8 app that uses ListBox, and need to minimize changes. For new apps in Windows 10, we recommend using the ListView control instead.

If you need to handle pointer events for a UIElement in a scrollable view (such as a ScrollViewer), you must explicitly disable support for manipulation events on the element in the view by calling UIElement.CancelDirectmanipulation(). To re-enable manipulation events in the view, call UIElement.TryStartDirectManipulation().

Using a ListBox

Use a ListBox control to present a list of items that a user can select from. More than one item in a ListBox control is visible at a time. You specify whether the ListBox control allows multiple selections by setting the SelectionMode property. You can get or set the selected items for the list box by using the SelectedItems property.

Populating a ListBox

You populate the ListBox control by adding UIElement items directly to the Items collection, or by binding the ItemsSource property to a data source. ItemsSource items from data will initially clear the Items collection when the binding is evaluated, so don't set both properties.

ListBox has a dedicated control for its items, ListBoxItem. But when you populate the Items collection, you can use elements or data, you don't typically use explicit ListBoxItem objects. What happens internally is that when the ListBox composes its visual tree from its templates, specifically when expanding the ItemTemplate, it creates a ListBoxItem wrapper for each of the objects it's including as items. At run time, the Items collection still contains the original items you declared. The created ListBoxItem wrappers are deeper in the visual tree, inside the items panel (see ItemsPanel) as its children. You don't usually need direct access to a ListBoxItem object. But if you want to access the created ListBoxItem wrappers, you can use Microsoft UI Automation techniques, or use VisualTreeHelper APIs, to walk into the object tree representation and find them.

ListBox vs. ListView and GridView

ListBox has many similarities with ListView or GridView (they share the parent class ItemsControl), but each control is oriented towards different scenarios. ListBox is best for general UI composition, particularly when the elements are always intended to be selectable, whereas ListView or GridView are best for data binding scenarios, particularly if virtualization or large data sets are involved. For more info on virtualization, see Using virtualization with a list or grid.

Version history

Windows version	SDK version	Value added
1607	14393	SingleSelectionFollowsFocus

-examples

Tip

For more info, design guidance, and code examples, see List box.

[!div class="nextstepaction"] Open the WinUI 2 Gallery app and see the ListBox in action

The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.

This example demonstrates how to add a collection of FontFamily objects directly to a ListBox control.

<ListBox>
    <TextBlock Text="Arial" FontFamily="Arial"/>
    <TextBlock Text="Courier New" FontFamily="Courier New"/> 
    <TextBlock Text="Times New Roman" FontFamily="Times New Roman"/>
</ListBox>

This example uses data binding to fill a ListBox control with a collection of FontFamily objects.

<ListBox x:Name="FontsList" Height="20" Width="150" 
         ItemsSource="{x:Bind fonts}" DisplayMemberPath="Source"/>

ObservableCollection<FontFamily> fonts = new ObservableCollection<FontFamily>();

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

Dim fonts As New ObservableCollection(of FontFamily) 

Public Sub New()
    MyBase.New()
    InitializeComponent()    
    fonts.Add(New FontFamily("Arial"))
    fonts.Add(New FontFamily("Courier New"))
    fonts.Add(New FontFamily("Times New Roman"))
End Sub

-see-also

Selector, ItemsControl, ListBoxItem, ComboBox, Controls list, Controls by function