AdaptiveGridView XAML Control

The AdaptiveGridView Control presents items in a evenly-spaced set of columns to fill the total available display space. It reacts to changes in the layout as well as the content so it can adapt to different form factors automatically.

There are 3 ways to use this Control:

  1. You can set DesiredWidth and ItemHeight, which will scale the width of each item and adjust the number of columns on demand using all horizontal space.

  2. You can set DesiredWidth only. This will mean that rows will take up as much space as required, using all horizontal space.

  3. Using OneRowModeEnabled, you can set DesiredWidth and ItemHeight which will adjust the width of each item and the number of visible columns on demand, using all horizontal space.

Syntax

<Page ...
     xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls"/>

<controls:AdaptiveGridView  Name="AdaptiveGridViewControl"
    ItemHeight="200"
    DesiredWidth="300"
    ItemTemplate="{StaticResource PhotosTemplate}">
</controls:AdaptiveGridView>

Sample Output

AdaptiveGridView animation

Properties

Property Type Description
DesiredWidth double Gets or sets the desired width of each item
ItemClickCommand ICommand Gets or sets the command to execute when an item is clicked and the IsItemClickEnabled property is true
ItemHeight double Gets or sets the height of each item in the grid
ItemsPanel ItemsPanelTemplate Gets the template that defines the panel that controls the layout of items
OneRowModeEnabled Boolean Gets or sets a value indicating whether only one row should be displayed
StretchContentForSingleRow Boolean Gets or sets a value indicating whether the control should stretch the content to fill at least one row

Important

ItemHeight property must be set when OneRowModeEnabled property set as true

Examples

  1. Using DesiredWidth in combination with ItemHeight:

    AdaptiveGridView DesiredHeight and ItemHeight

  2. Maintain aspect ratio by setting DesiredWidth with no ItemHeight set:

    AdaptiveGridView Viewbox scaled

    This still requires the ItemTemplate to contain some scaling logic, this can be done with Height and Width set on the content inside of a Viewbox, or using custom view logic.

    • Using a Viewbox:

      Using the Height and Width properties of content inside of a Viewbox means that the content inside will scale linearly when Width and Height changes, which causes a zoom-like effect. This might not be a desired effect, and it will also likely incur a slight performance penalty.

      ItemTemplate implementation

      <DataTemplate x:Key="PhotosTemplate">
          <Viewbox>
              <Grid
                  Height="300"
                  Width="200"
                  Background="White"
                  BorderBrush="Black"
                  BorderThickness="1">
                  <Image
                      Source="{Binding Thumbnail}"
                      Stretch="UniformToFill"
                      HorizontalAlignment="Center"
                      VerticalAlignment="Center"/>
              </Grid>
          </Viewbox>
      </DataTemplate>
      
    • To use custom view logic:

      Using MeasureOverride on a ContentControl allows you to specify the Width and Height of the content, which might reap better performance compared to a Viewbox. The dimensions of the content space will change uniformly, but the content will not zoom.

      Custom logic implementation

      public class AspectContentControl : ContentControl
      {
          protected override Size MeasureOverride(Size availableSize)
          {
              return new Size(availableSize.Width, availableSize.Width * 1.6);
          }
      }
      
      Public Class AspectContentControl
          Inherits ContentControl
      
          Protected Overrides Function MeasureOverride(ByVal availableSize As Size) As Size
              Return New Size(availableSize.Width, availableSize.Width * 1.6)
          End Function
      End Class
      

      ItemTemplate implementation

      <DataTemplate x:Key="PhotosTemplate">
          <local:AspectContentControl 
              HorizontalContentAlignment="Stretch" 
              VerticalContentAlignment="Stretch">
              <Grid Background="White"
                  BorderBrush="Black"
                  BorderThickness="1">
                  <Image
                      Source="{Binding Thumbnail}"
                      Stretch="UniformToFill" />
              </Grid>
          </local:AspectContentControl>
      </DataTemplate>
      
  3. Using OneRowModeEnabled:

    AdaptiveGridView OneRowMode

    If there are not enough items to fill one row, the control will stretch the items until all available space is filled. This can result in much wider items than specified. If you prefer your items to always stay close to the DesiredWidth, you can set the StretchContentForSingleRow property to false, to prevent further stretching.

Sample Code

AdaptiveGridView Sample Page Source. You can see this in action in Windows Community Toolkit Sample App.

Requirements

Device family Universal, 10.0.16299.0 or higher
Namespace Microsoft.Toolkit.Uwp.UI.Controls
NuGet package Microsoft.Toolkit.Uwp.UI.Controls

API