How to add a list view (XAML)

[ 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 view to a Windows Runtime app using C++, C#, or Visual Basic.

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

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

• Roadmap for Windows Runtime apps using C# or Visual Basic
• Roadmap for Windows Runtime apps using C++

What you need to know

Technologies

• ListView

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 view in XAML

To add a list view in XAML

1. Add a ListView control to a parent container.

2. To assign a name to the list view, 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.

3. Add items to the list view 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.

   <ListView x:Name="listView1" SelectionChanged="ListView_SelectionChanged">
       <x:String>Item 1</x:String>
       <x:String>Item 2</x:String>
   </ListView>
   

   Here's an example of how to bind the ItemsSource to a collection in XAML. The ItemsSource is bound to the DataContext of the ListView.

   <ListView ItemsSource="{Binding}" SelectionChanged="ListView_SelectionChanged"/>
   

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

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

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

   Private Sub ListView_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 view in code

To add a list view in code

1. Create a new ListView.

2. Add items to the list view by populating the Items collection or by setting the ItemsSource property to a data collection.

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

4. Add the ListView to a parent container in the visual tree. This is required to make the list view show in the UI.

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

   // Create a new list view, add content, 
   // and add a SelectionChanged event handler.
   ListView^ listView1 = ref new ListView();
   listView1->Items->Append("Item 1");
   listView1->Items->Append("Item 2");
   listView1->SelectionChanged += 
       ref new SelectionChangedEventHandler(this, &MainPage::ListView_SelectionChanged);
   
   // Add the list view to a parent container in the visual tree.
   stackPanel1->Children->Append(listView1);
   

   // Create a new list view, add content, 
   // and add a SelectionChanged event handler.
   ListView listView1 = new ListView();
   listView1.Items.Add("Item 1");
   listView1.Items.Add("Item 2");
   listView1.SelectionChanged += ListView_SelectionChanged;
   
   // Add the list view to a parent container in the visual tree.
   stackPanel1.Children.Add(listView1);
   

   ' Create a new list view, add content, 
   ' and add a SelectionChanged event handler.
   Dim listView1 = New ListView()
   listView1.Items.Add("Item 1")
   listView1.Items.Add("Item 2")
   AddHandler listView1.SelectionChanged, AddressOf Me.ListView_SelectionChanged
   
   ' Add the list view to a parent container in the visual tree.
   stackPanel1.Children.Add(listView1)
   

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

   // Data source.
   Platform::Collections::Vector<String^>^ itemsList = 
       ref new Platform::Collections::Vector<String^>();
   itemsList->Append("Item 1");
   itemsList->Append("Item 2");
   
   // Create a new list view, add content, 
   // and add a SelectionChanged event handler.
   ListView^ listView1 = ref new ListView();
   listView1->ItemsSource = itemsList;
   listView1->SelectionChanged += 
       ref new SelectionChangedEventHandler(this, &MainPage::ListView_SelectionChanged);
   
   // Add the list view to a parent container in the visual tree.
   stackPanel1->Children->Append(listView1);
   

   // Data source.
   List<String> itemsList = new List<string>();
   itemsList.Add("Item 1");
   itemsList.Add("Item 2");
   
   // Create a new list view, add content, 
   // and add a SelectionChanged event handler.
   ListView listView1 = new ListView();
   listView1.ItemsSource = itemsList;
   listView1.SelectionChanged += ListView_SelectionChanged;
   
   // Add the list view to a parent container in the visual tree.
   stackPanel1.Children.Add(listView1);
   

   ' Data source.
   Dim itemsList = New List(Of String)()
   itemsList.Add("Item 1")
   itemsList.Add("Item 2")
   
   ' Create a new list view, add content, 
   ' and add a SelectionChanged event handler.
   Dim listView1 = New ListView()
   listView1.ItemsSource = itemsList
   AddHandler listView1.SelectionChanged, AddressOf Me.ListView_SelectionChanged
   
   ' Add the list view to a parent container in the visual tree.
   stackPanel1.Children.Add(listView1)
   

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

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

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

   Private Sub ListView_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 view using a design tool

To add a list view using a design tool

1. Select the ListView control.

   • In Microsoft Visual Studio, select the ListView in the Toolbox pane.

   • In Blend for Visual Studio, select the ListView in the Assets pane.

     Select Controls in the left side of the Assets pane if it's not selected.

2. Add a ListView to the design surface. Do one of these:

   • Double-click the list view. The list view is added to the selected parent container with default position and size settings.
   • Drag the list view to the design surface and drop it. The list view is added in the position where you drop it with default size settings.
   • Draw the list view control onto the design surface. The list view is added with the size and position settings that you draw.

3. If you need to, assign a name to the ListView. With the list view 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.

4. Add items to the list view by populating the Items collection or by binding the ItemsSource property to a data source.

5. To perform an action when the list view 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 view 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 to add a handler with a custom name.

Related topics

ListView

Quickstart: Adding ListView and GridView controls

Roadmap for Windows Runtime apps using C# or Visual Basic

Roadmap for Windows Runtime apps using C++