Edit

CollectionView

Browse sample. Browse the sample

The .NET Multi-platform App UI (.NET MAUI) CollectionView is a view for presenting lists of data using different layout specifications. It aims to provide a more flexible, and performant alternative to ListView.

The following screenshot shows a CollectionView that uses a two-column vertical grid and allows multiple selections:

Screenshot of a CollectionView vertical grid layout.

CollectionView should be used for presenting lists of data that require scrolling or selection. A bindable layout can be used when the data to be displayed doesn't require scrolling or selection. For more information, see BindableLayout.

Note

On iOS and Mac Catalyst, the optimized handlers that were optional in .NET 9 are the default handlers for CollectionView in .NET 10, providing improved performance and stability.

Revert to .NET 9 behavior

We recommend using the new handler for CollectionView, but if you want to opt-out of this behavior and revert back to the .NET 9 handler, you can use the code below in your MauiProgram.cs.

#if IOS || MACCATALYST
builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler>();
});
#endif

Windows CollectionView handler in .NET 11

In .NET MAUI 11, Windows uses the Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2 handler for CollectionView by default. The handler is controlled by the Microsoft.Maui.RuntimeFeature.IsWindowsCollectionView2HandlerEnabled AppContext switch, which is on by default. The UseWindowsCollectionView2Handler MSBuild property maps to this switch.

This WinUI ItemsRepeater-based handler improves virtualization and scrolling behavior, and aligns the Windows CollectionView architecture with the optimized handlers on other platforms. Selection visuals are also different from the legacy Windows handler: selected items are highlighted with a border that wraps the item, and the multiple-selection UI differs from the previous ListView-based handler.

If your app depends on legacy Windows CollectionView behavior or custom handler assumptions, temporarily opt out while migrating by setting the UseWindowsCollectionView2Handler MSBuild property to false in your project file:

<PropertyGroup>
    <UseWindowsCollectionView2Handler>false</UseWindowsCollectionView2Handler>
</PropertyGroup>

CollectionView and ListView differences

While the CollectionView and ListView APIs are similar, there are some notable differences:

  • CollectionView has a flexible layout model, which allows data to be presented vertically or horizontally, in a list or a grid.
  • CollectionView supports single and multiple selection.
  • CollectionView has no concept of cells. Instead, a data template is used to define the appearance of each item of data in the list.
  • CollectionView automatically utilizes the virtualization provided by the underlying native controls.
  • CollectionView reduces the API surface of ListView. Many properties and events from ListView are not present in CollectionView.
  • CollectionView does not include built-in separators.
  • CollectionView will throw an exception if its ItemsSource is updated off the UI thread.

Move from ListView to CollectionView

ListView implementations can be migrated to CollectionView implementations with the help of the following table:

Concept ListView API CollectionView
Data ItemsSource A CollectionView is populated with data by setting its ItemsSource property. For more information, see Populate a CollectionView with data.
Item appearance ItemTemplate The appearance of each item in a CollectionView can be defined by setting the ItemTemplate property to a DataTemplate. For more information, see Define item appearance.
Cells TextCell, ImageCell, ViewCell CollectionView has no concept of cells, and therefore no concept of disclosure indicators. Instead, a data template is used to define the appearance of each item of data in the list.
Row separators SeparatorColor, SeparatorVisibility CollectionView does not include built-in separators. These can be provided, if desired, in the item template.
Selection SelectionMode, SelectedItem CollectionView supports single and multiple selection. For more information, see Configure CollectionView item selection.
Row height HasUnevenRows, RowHeight In a CollectionView, the row height of each item is determined by the ItemSizingStrategy property. For more information, see Item sizing.
Caching CachingStrategy CollectionView automatically uses the virtualization provided by the underlying native controls.
Headers and footers Header, HeaderElement, HeaderTemplate, Footer, FooterElement, FooterTemplate CollectionView can present a header and footer that scroll with the items in the list, via the Header, Footer, HeaderTemplate, and FooterTemplate properties. For more information, see Headers and footers.
Grouping GroupDisplayBinding, GroupHeaderTemplate, GroupShortNameBinding, IsGroupingEnabled CollectionView displays correctly grouped data by setting its IsGrouped property to true. Group headers and group footers can be customized by setting the GroupHeaderTemplate and GroupFooterTemplate properties to DataTemplate objects. For more information, see Display grouped data in a CollectionView.
Pull to refresh IsPullToRefreshEnabled, IsRefreshing, RefreshAllowed, RefreshCommand, RefreshControlColor, BeginRefresh(), EndRefresh() Pull to refresh functionality is supported by setting a CollectionView as the child of a RefreshView. For more information, see Pull to refresh.
Context menu items ContextActions Context menu items are supported by setting a SwipeView as the root view in the DataTemplate that defines the appearance of each item of data in the CollectionView. For more information, see Context menus.
Scrolling ScrollTo() CollectionView defines ScrollTo methods, which scroll items into view. For more information, see Control scrolling in a CollectionView.
  • Last updated on