How to add a list box (XAML)

Article
03/01/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

This tutorial walks you through the steps to add a list box to a Windows Runtime app using C++, C#, or Visual Basic.

You typically add a list box in the Extensible Application Markup Language (XAML) editor or using a design tool like Blend for Visual Studio. You can also add a list box in code at runtime.

Roadmap: How does this topic relate to others? See:

What you need to know

Technologies

ListBox

Prerequisites

We assume that you can add controls to a basic Windows Runtime app using C++, C#, or Visual Basic. For instructions on adding a control, see Quickstart: Adding controls and handling events.

Instructions

Step 1: Add a list box in XAML

To add a list box in XAML

Add a ListBox control to a parent container.
To assign a name to the list box, set the x:Name attribute to a string value.

To refer to a control in code, it must have a name. Otherwise, a name is not required.
Add items to the list box by populating the Items collection or by binding the ItemsSource property to a data source.

Here's an example of how to populate the Items collection in XAML.
```
<ListBox x:Name="listBox1" SelectionChanged="ListBox_SelectionChanged" Width="100">
    <x:String>Item 1</x:String>
    <x:String>Item 2</x:String>
    <x:String>Item 3</x:String>
</ListBox>
```
Here's an example of how to bind the ItemsSource to a collection in XAML. The ItemsSource is bound to the DataContext of the ListBox.
```
<ListBox ItemsSource="{Binding}" SelectionChanged="ListBox_SelectionChanged" Width="100"/>
```

To perform an action when the list box selection changes, add a handler for the SelectionChanged event. In the SelectionChanged event handler, add code to perform some action.

void MainPage::ListBox_SelectionChanged(Object^ sender, SelectionChangedEventArgs^ e)
{
    // Add code to perform some action here.
}

private void ListBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    // Add code to perform some action here.
}

Private Sub ListBox_SelectionChanged()
    ' Add code to perform some action here.
End Sub

To check the selected item of the control outside of the SelectionChanged event, use the SelectedItem or SelectedIndex properties.

Step 2: Add a list box in code

To add a list box in code

Create a new ListBox.
Add items to the list box by populating the Items collection or by setting the ItemsSource property to a data collection.
To perform an action when the list box selection changes, add a handler for the SelectionChanged event. In the SelectionChanged event handler, add code to perform some action.

Add the ListBox to a parent container in the visual tree to make the list box show in the UI.

Here's an example of how to add a ListBox and populate the Items collection in code.

// Create a new list box, add items, and add a SelectionChanged handler.
ListBox^ listBox1 = ref new ListBox();
listBox1->Items->Append("Item 1");
listBox1->Items->Append("Item 2");
listBox1->Items->Append("Item 3");
listBox1->Width = 140;
listBox1->SelectionChanged += 
    ref new SelectionChangedEventHandler(this, &MainPage::ListBox_SelectionChanged);

// Add the list box to a parent container in the visual tree.
stackPanel1->Children->Append(listBox1);

// Create a new list box, add items, and add a SelectionChanged handler.
ListBox listBox1 = new ListBox();
listBox1.Items.Add("Item 1");
listBox1.Items.Add("Item 2");
listBox1.Items.Add("Item 3");
listBox1.Width = 140;
listBox1.SelectionChanged += ListBox_SelectionChanged;

// Add the list box to a parent container in the visual tree.
stackPanel1.Children.Add(listBox1);

' Create a new list box, add items, and add a SelectionChanged handler.
Dim listBox1 = New ListBox()
listBox1.Items.Add("Item 1")
listBox1.Items.Add("Item 2")
listBox1.Items.Add("Item 3")
listBox1.Width = 140
AddHandler listBox1.SelectionChanged, AddressOf Me.ListBox_SelectionChanged

' Add the list box to a parent container in the visual tree.
stackPanel1.Children.Add(listBox1)

Here's an example of how to add a ListBox and set the ItemsSource in code.

// Data collection
Platform::Collections::Vector<String^>^ fonts = 
    ref new Platform::Collections::Vector<String^>();
fonts->Append("Item 1");
fonts->Append("Item 2");
fonts->Append("Item 3");

// Create a new list box, set it's items source, and add a SelectionChanged handler.
ListBox^ listBox1 = ref new ListBox();
listBox1->Width = 140;
listBox1->ItemsSource = fonts;
listBox1->SelectionChanged += 
    ref new SelectionChangedEventHandler(this, &MainPage::ListBox_SelectionChanged);

// Add the list box to a parent container in the visual tree.
stackPanel1->Children->Append(listBox1);

// Data collection
List<string> fonts = new List<string>();
fonts.Add("Item 1");
fonts.Add("Item 2");
fonts.Add("Item 3");

// Create a new list box, set it's items source, and add a SelectionChanged handler.
ListBox listBox1 = new ListBox();
listBox1.Width = 140;
listBox1.ItemsSource = fonts;
listBox1.SelectionChanged += ListBox_SelectionChanged;

// Add the list box to a parent container in the visual tree.
stackPanel1.Children.Add(listBox1);

' Data collection
Dim fonts = New List(Of String)()
fonts.Add("Item 1")
fonts.Add("Item 2")
fonts.Add("Item 3")

' Create a new list box, set it's items source, and add a SelectionChanged handler.
Dim listBox1 = New ListBox()
listBox1.Width = 140
listBox1.ItemsSource = fonts
AddHandler listBox1.SelectionChanged, AddressOf Me.ListBox_SelectionChanged

' Add the list box to a parent container in the visual tree.
stackPanel1.Children.Add(listBox1)

void MainPage::ListBox_SelectionChanged(Object^ sender, SelectionChangedEventArgs^ e)
{
    // Add code to perform some action here.
}

private void ListBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    // Add code to perform some action here.
}

Private Sub ListBox_SelectionChanged()
    ' Add code to perform some action here.
End Sub

To check the selected item of the control outside of the SelectionChanged event, use the SelectedItem or SelectedIndex properties.

Step 3: Add a list box using a design tool

To add a list box using a design tool

Select the ListBox control.
- In Microsoft Visual Studio, pick the ListBox in the Toolbox pane.
  
  You might need to expand the All XAML Controls section if it's collapsed.
- In Blend for Visual Studio, pick the ListBox in the Assets pane.
  
  Select Controls in the left side of the Assets pane if it's not selected.
Add a ListBox to the design surface. Do one of these:
- Double-click the list box. The list box is added to the selected parent container with default position and size settings.
- Drag the list box to the design surface and drop it. The list box is added in the position where you drop it with default size settings.
- Draw the list box control onto the design surface. The list box is added with the size and position settings that you draw.
If you need to, assign a name to the ListBox. With the list box selected, type the name into the Name property text box.

The Name property text box is at the top of the Properties pane. To refer to a control in code, it must have a name. Otherwise, a name is not required.
Add items to the list box by populating the Items collection or by binding the ItemsSource property to a data source.
To perform an action when the list box selection changes, add a handler for the SelectionChanged event. In the SelectionChanged event handler, add code to perform some action.
1. Select the Event view in the Property pane.
2. With the list box selected on the design surface, do one of these:
  - Double click the SelectionChanged event text box to add a handler with a default name.
  - Type a name into the SelectionChanged event text box and press enter to add a handler with a custom name.

ListBox

Roadmap for Windows Runtime apps using C# or Visual Basic

Roadmap for Windows Runtime apps using C++