Set CollectionView layout - .NET MAUI (2023)

Browse the sample

The .NET Multi-Platform App (.NET MAUI) user interfaceCollectionViewdefines the following properties that control the layout:

• article layout, Typarticle layout, specifies the layout to use.
• ItemSizingStrategy, TypItemSizingStrategy, specifies the item measurement strategy to use.

These properties are supported byBindablePropertyObjects, meaning the properties can be data binding targets.

By default, aCollectionViewdisplays its items in a vertical list. However, one of the following layouts can be used:

• Vertical List - a single-column list that grows vertically as new items are added.
• Horizontal list - a single-line list that grows horizontally as new items are added.
• Vertical Grid - a multi-column grid that grows vertically as new items are added.
• Horizontal Grid - a multi-line grid that grows horizontally as new items are added.

These layouts can be specified by settingarticle layoutProperty on class derived fromarticle layoutClass. This class defines the following properties:

• orientation, TypItemsLayoutOrientation, indicates the direction in which theCollectionViewexpands as items are added.
• SnapPointsAlignment, TypSnapPointsAlignment, specifies how snap points are aligned to elements.
• SnapPointsType, TypSnapPointsType, sets the behavior of snap points when scrolling.

These properties are supported byBindablePropertyObjects, meaning the properties can be data binding targets. For more information on snap points, seesnap pointsInControl scrolling in a CollectionView.

TheItemsLayoutOrientationEnumeration defines the following members:

• Verticalpoints out that theCollectionViewexpands vertically as items are added.
• Horizontalpoints out that theCollectionViewexpands horizontally as items are added.

TheLinearItemsLayoutclass inherits from thearticle layoutclass and defines aItemSpacingproperty, typedouble, which represents the empty space around each element. The default value of this property is 0 and its value must always be greater than or equal to 0LinearItemsLayoutclass also defines staticVerticalAndHorizontalmembers. These members can be used to create vertical or horizontal lists, respectively. Alternatively aLinearItemsLayoutObject can be created by specifying aItemsLayoutOrientationEnumeration member as argument.

TheGridItemsLayoutclass inherits from thearticle layoutclass and defines the following properties:

• VerticalItemSpacing, Typdouble, which represents the vertical empty space around each element. The default value of this property is 0 and its value must always be greater than or equal to 0.
• HorizontalItemSpacing, Typdouble, which represents the horizontal empty space around each element. The default value of this property is 0 and its value must always be greater than or equal to 0.
• Teams, Typint, which represents the number of columns or rows to display in the grid. The default value of this property is 1, and its value must always be greater than or equal to 1.

These properties are supported byBindablePropertyObjects, meaning the properties can be data binding targets.

vertical list

By default,CollectionViewdisplays its items in a vertical list layout. Therefore, there is no need to set thisarticle layoutProperty to use this layout:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.ItemTemplate> <DataTemplate> <Grid Padding="10"> <Grid.RowDefinitions> <RowDefinition Height="Auto" /> <RowDefinition Height="Auto" /> </Grid.RowDefinitions> <Grid.ColumnDefinitions> <ColumnDefinition Width="Auto" /> <ColumnDefinition Width="Auto" /> </Grid.ColumnDefinitions> <Image Grid.RowSpan="2" Source="{Binding ImageUrl }" Aspect="AspectFill" HeightRequest="60" WidthRequest="60" /> <Label Grid.Column="1" Text="{Binding Name}" FontAttributes="Bold" /> <Label Grid.Row=" 1" Grid.Column="1" Text="{Binding Location}" FontAttributes="Italic" VerticalOptions="End" /> </Grid> </DataTemplate> </CollectionView.ItemTemplate></CollectionView>

However, for the sake of completeness in XAML aCollectionViewcan be set to display its items in a vertical list by setting itsarticle layoutproperty toVerticalLists:

<CollectionView ItemsSource="{Binding Monkeys}" ItemsLayout="VerticalList"> ...</CollectionView>

Alternatively, this can also be achieved by setting thearticle layoutownership of aLinearItemsLayoutObject stating theVertical ItemsLayoutOrientationenumeration member asorientationproperty value:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.ItemsLayout> <LinearItemsLayout Orientation="Vertical" /> </CollectionView.ItemsLayout> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ ... ItemsLayout = LinearItemsLayout.Vertical};

This results in a single-column list that grows vertically as new items are added:

Horizontal list

In XAML, aCollectionViewcan display its items in a horizontal list by setting itsarticle layoutproperty toHorizontaleListe:

<CollectionView ItemsSource="{Binding Monkeys}" ItemsLayout="HorizontalList"> <CollectionView.ItemTemplate> <DataTemplate> <Grid Padding="10"> <Grid.RowDefinitions> <RowDefinition Height="35" /> <RowDefinition Height= "35" /> </Grid.RowDefinitions> <Grid.ColumnDefinitions> <ColumnDefinition Width="70" /> <ColumnDefinition Width="140" /> </Grid.ColumnDefinitions> <Image Grid.RowSpan="2" Quelle ="{Binding ImageUrl}" Aspect="AspectFill" HeightRequest="60" WidthRequest="60" /> <Label Grid.Column="1" Text="{Binding Name}" FontAttributes="Bold" LineBreakMode="TailTruncation " /> <Label Grid.Row="1" Grid.Column="1" Text="{Binding Location}" LineBreakMode="TailTruncation" FontAttributes="Italic" VerticalOptions="End" /> </Grid> </ DataTemplate> </CollectionView.ItemTemplate></CollectionView>

Alternatively, this layout can also be achieved by setting thearticle layoutownership of aLinearItemsLayoutObject stating theHorizontal ItemsLayoutOrientationenumeration member asorientationproperty value:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.ItemsLayout> <LinearItemsLayout Orientation="Horizontal" /> </CollectionView.ItemsLayout> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ ... ItemsLayout = LinearItemsLayout.Horizontal};

This results in a single line list that grows horizontally as new items are added:

Vertical Grid

In XAML, aCollectionViewcan display its elements in a vertical grid by setting itsarticle layoutproperty toVerticalGrid:

<CollectionView ItemsSource="{Binding Monkeys}" ItemsLayout="VerticalGrid, 2"> <CollectionView.ItemTemplate> <DataTemplate> <Grid Padding="10"> <Grid.RowDefinitions> <RowDefinition Height="35" /> <RowDefinition Height="35" /> </Grid.RowDefinitions> <Grid.ColumnDefinitions> <ColumnDefinition Width="70" /> <ColumnDefinition Width="80" /> </Grid.ColumnDefinitions> <Image Grid.RowSpan="2 " Source="{Binding ImageUrl}" Aspect="AspectFill" HeightRequest="60" WidthRequest="60" /> <Label Grid.Column="1" Text="{Binding Name}" FontAttributes="Bold" LineBreakMode= "TailTruncation" /> <Label Grid.Row="1" Grid.Column="1" Text="{Binding Location}" LineBreakMode="TailTruncation" FontAttributes="Italic" VerticalOptions="End" /> </Grid> </DataTemplate> </CollectionView.ItemTemplate></CollectionView>

Alternatively, this layout can also be achieved by setting thearticle layoutownership of aGridItemsLayoutobject oforientationproperty is setVertical:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.ItemsLayout> <GridItemsLayout Orientation="Vertical" Span="2" /> </CollectionView.ItemsLayout> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ ... ItemsLayout = new GridItemsLayout (2, ItemsLayoutOrientation.Vertical)};

A vertical by defaultGridItemsLayoutdisplays items in a single column. However, this example sets theGridItemsLayout.Spanproperty to 2. This results in a two-column grid that grows vertically as new items are added:

Horizontal grid

In XAML, aCollectionViewcan display its elements in a horizontal grid by setting itsarticle layoutproperty toHorizontalGrid:

<CollectionView ItemsSource="{Binding Monkeys}" ItemsLayout="HorizontalGrid, 4"> <CollectionView.ItemTemplate> <DataTemplate> <Grid Padding="10"> <Grid.RowDefinitions> <RowDefinition Height="35" /> <RowDefinition Height="35" /> </Grid.RowDefinitions> <Grid.ColumnDefinitions> <ColumnDefinition Width="70" /> <ColumnDefinition Width="140" /> </Grid.ColumnDefinitions> <Image Grid.RowSpan="2 " Source="{Binding ImageUrl}" Aspect="AspectFill" HeightRequest="60" WidthRequest="60" /> <Label Grid.Column="1" Text="{Binding Name}" FontAttributes="Bold" LineBreakMode= "TailTruncation" /> <Label Grid.Row="1" Grid.Column="1" Text="{Binding Location}" LineBreakMode="TailTruncation" FontAttributes="Italic" VerticalOptions="End" /> </Grid> </DataTemplate> </CollectionView.ItemTemplate></CollectionView>

Alternatively, this layout can also be achieved by setting thearticle layoutownership of aGridItemsLayoutobject oforientationproperty is setHorizontal:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.ItemsLayout> <GridItemsLayout Orientation="Horizontal" Span="4" /> </CollectionView.ItemsLayout> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ ... ItemsLayout = new GridItemsLayout (4, ItemsLayoutOrientation.Horizontal)};

A horizontal one by defaultGridItemsLayoutdisplays items on a single line. However, this example sets theGridItemsLayout.Spanproperty to 4. This results in a four-row grid that grows horizontally as new items are added:

CollectionViewcan render a header and footer that scroll with the items in the list. The header and footer can be strings, views, ordata templateobjects.

CollectionViewdefines the following properties for specifying the header and footer:

• Header, TypObject, specifies the string, binding, or view that appears at the top of the list.
• header template, Typdata template, specifies thedata templateto use to format theHeader.
• Footer, TypObject, specifies the string, binding, or view that appears at the end of the list.
• footer template, Typdata template, specifies thedata templateto use to format theFooter.

These properties are supported byBindablePropertyObjects, meaning the properties can be data binding targets.

When a header is added to a layout that grows horizontally from left to right, the header appears to the left of the list. Similarly, when a footer is added to a layout that grows horizontally from left to right, the footer appears to the right of the list.

Show strings in header and footer

TheHeaderAndFooterProperties can be adjustedlineValues ​​as shown in the following example:

<CollectionView ItemsSource="{Binding Monkeys}" Header="Monkeys" Footer="2019"> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ Header = "Monkeys", Footer = "2019"};collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");

This code results in the following screenshots, showing the header in the iOS screenshot and the footer in the Android screenshot:

Display views in the header and footer

TheHeaderAndFooterProperties can be set on a view at a time. This can be a single view or a view that contains multiple child views. The following example shows theHeaderAndFooterProperties each set to aStackLayoutObject containing alabelObject:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.Header> <StackLayout BackgroundColor="LightGray"> <Label Margin="10,0,0,0" Text="Monkeys" FontSize="12" FontAttributes=" Bold" /> </StackLayout> </CollectionView.Header> <CollectionView.Footer> <StackLayout BackgroundColor="LightGray"> <Label Margin="10,0,0,0" Text="Friends of Xamarin Monkey" FontSize= "12" FontAttributes="Bold" /> </StackLayout> </CollectionView.Footer> ...</CollectionView>

The corresponding C# code is:

StackLayout headerStackLayout = new StackLayout();header.StackLayout.Add(new Label { Text = "Monkeys", ... } );StackLayout footerStackLayout = new StackLayout();footerStackLayout.Add(new Label { Text = "Friends of Xamarin Monkey", ... } );CollectionView collectionView = new CollectionView{ Header = headerStackLayout, Footer = footerStackLayout };collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");

This code results in the following screenshots, showing the header in the iOS screenshot and the footer in the Android screenshot:

Display a template-based header and footer

Theheader templateAndfooter templateProperties can be adjusteddata templateObjects used to format the header and footer. In this scenario, theHeaderAndFooterProperties must be bound to the current source for the templates to be applied, as shown in the following example:

<CollectionView ItemsSource="{Binding Monkeys}" Header="{Binding .}" Footer="{Binding .}"> <CollectionView.HeaderTemplate> <DataTemplate> <StackLayout BackgroundColor="LightGray"> <Label Margin="10, 0,0,0" Text="Monkeys" FontSize="12" FontAttributes="Bold" /> </StackLayout> </DataTemplate> </CollectionView.HeaderTemplate> <CollectionView.FooterTemplate> <DataTemplate> <StackLayout BackgroundColor=" LightGray"> <Label Margin="10,0,0,0" Text="Friends of Xamarin Monkey" FontSize="12" FontAttributes="Bold" /> </StackLayout> </DataTemplate> </CollectionView.FooterTemplate> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ HeaderTemplate = new DataTemplate(() => { return new StackLayout { }; }), FooterTemplate = new DataTemplate(() => { return new StackLayout { }; })};collectionView.SetBinding(ItemsView .HeaderProperty, ".");collectionView.SetBinding(ItemsView.FooterProperty, ".");collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Affen");

This code results in the following screenshots, showing the header in the iOS screenshot and the footer in the Android screenshot:

Elementabstand

By default, there is no space between each element in aCollectionView. This behavior can be changed by setting properties on the element layout used byCollectionView.

When aCollectionViewputs hisarticle layoutownership of aLinearItemsLayoutobject thatLinearItemsLayout.ItemSpacingProperty can be set to adoubleValue representing the distance between elements:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.ItemsLayout> <LinearItemsLayout Orientation="Vertical" ItemSpacing="20" /> </CollectionView.ItemsLayout> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ ... ItemsLayout = new LinearItemsLayout (ItemsLayoutOrientation.Vertical) { ItemSpacing = 20 }};

This code results in a vertical single-column list with 20 spacing between items:

When aCollectionViewputs hisarticle layoutownership of aGridItemsLayoutobject thatGridItemsLayout.VerticalItemSpacingAndGridItemsLayout.HorizontalItemSpacingProperties can be adjusteddoubleValues ​​representing the empty space vertically and horizontally between elements:

<CollectionView ItemsSource="{Binding Monkeys}"> <CollectionView.ItemsLayout> <GridItemsLayout Orientation="Vertical" Span="2" VerticalItemSpacing="20" HorizontalItemSpacing="30" /> </CollectionView.ItemsLayout> ...< /CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ ... ItemsLayout = new GridItemsLayout (2, ItemsLayoutOrientation.Vertical) { VerticalItemSpacing = 20, HorizontalItemSpacing = 30 }};

This code results in a vertical two-column grid with a vertical spacing of 20 between items and a horizontal spacing of 30 between items:

item size

By default, each element in aCollectionViewis individually measured and sized provided the UI elements in thedata templateDo not specify fixed sizes. This changeable behavior is specified by theCollectionView.ItemSizingStrategyproperty value. This property value can be set to one of theItemSizingStrategyList of members:

• MeasureAllItems- Each item is measured individually. This is the default value.
• MeasureFirstItem- only the first item is measured, all subsequent items will be given the same size as the first item.

The following code example shows how to set theItemSizingStrategyProperty:

<CollectionView ... ItemSizingStrategy="MeasureFirstItem"> ...</CollectionView>

The corresponding C# code is:

CollectionView collectionView = new CollectionView{ ... ItemSizingStrategy = ItemSizingStrategy.MeasureFirstItem};

Dynamic resizing of elements

Article in aCollectionViewcan be dynamically resized at runtime by changing layout-related properties of elements withindata template. For example, the following code example modifies theheight requestAndwidth requestproperties of aBildObject:

void OnImageTapped(object sender, EventArgs e){ Image image = sender as Image; image.HeightRequest = image.WidthRequest = image.HeightRequest.Equals(60) ? 100 : 60;}

TheOnImageTappedEvent handler is executed in response to aBildtapped object and resizes the image to make it easier to view:

Layout from right to left

CollectionViewcan arrange its content in a right-to-left flow direction by setting itsflow directionproperty toRight to left. However, theflow directionproperty should ideally be set on a page or root layout, making all elements within the page or root layout responsive to flow direction:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" x:Class="CollectionViewDemos.Views .VerticalListFlowDirectionPage" Title="Vertikale Liste (RTL FlowDirection)" FlowDirection="RightToLeft"> <StackLayout Margin="20"> <CollectionView ItemsSource="{Binding Monkeys}"> ... </CollectionView> </StackLayout>< /Inhaltsseite>

The standardflow directionis for an element with a parentMatchParent. therefore, theCollectionViewinherits theflow directionReal estate value from theStackLayout, which in turn inherits theflow directionReal estate value from thecontent page. This results in the right-to-left layout shown in the screenshot below: