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

You typically add a grid view in the Extensible Application Markup Language (XAML) editor or using a design tool like Blend for Visual Studio. You can also add a grid 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

• GridView

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

To add a grid view in XAML

1. Add a GridView control to a parent container.

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

   <GridView x:Name="gridView1" SelectionChanged="GridView_SelectionChanged">
       <x:String>Item 1</x:String>
       <x:String>Item 2</x:String>
   </GridView>
   

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

   <GridView ItemsSource="{Binding}" SelectionChanged="GridView_SelectionChanged"/>
   

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

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

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

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

To add a grid view in code

1. Create a new GridView.

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

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

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

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

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

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

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

   Here's an example of how to add a GridView 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 grid view, add content, 
   // and add a SelectionChanged event handler.
   GridView^ gridView1 = ref new GridView();
   gridView1->ItemsSource = itemsList;
   gridView1->SelectionChanged += 
       ref new SelectionChangedEventHandler(this, &MainPage::GridView_SelectionChanged);
   
   // Add the grid view to a parent container in the visual tree.
   stackPanel1->Children->Append(gridView1);
   

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

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

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

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

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

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

To add a grid view using a design tool

1. Select the GridView control.

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

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

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

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

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

3. If you need to, assign a name to the GridView. With the grid 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 grid view by populating the Items collection or by binding the ItemsSource property to a data source.

5. To perform an action when the grid 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 grid 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

GridView

Quickstart: Adding ListView and GridView controls

Roadmap for Windows Runtime apps using C# or Visual Basic

Roadmap for Windows Runtime apps using C++