--- name: maui-collectionview description: > Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: "CollectionView", "list view", "grid layout", "data template", "item template", "grouping", "pull to refresh", "incremental loading", "swipe actions", "empty view", "selection mode", "scroll to item", displaying scrollable data, replacing ListView. DO NOT USE FOR: simple static layouts without scrollable data (use Grid or StackLayout), map pin lists (use Microsoft.Maui.Controls.Maps), table-based data entry forms, non-MAUI list controls, CarouselView or BindableLayout questions, platform-specific handler or renderer customization, diagnosing CollectionView bugs in the MAUI framework itself, or general MVVM/binding questions that merely happen to mention a list (use maui-data-binding). license: MIT ---

# CollectionView — .NET MAUI

`CollectionView` is the primary control for displaying scrollable lists and grids of data in .NET MAUI. It replaces `ListView` with better performance, flexible layouts, and no `ViewCell` requirement.

## When to Use

- Displaying a scrollable list or grid of data items - Binding a collection of objects to a templated item layout - Adding selection (single or multiple), grouping, or pull-to-refresh - Implementing infinite scroll / incremental loading - Showing swipe actions on list items - Displaying an empty state when no data is available

## When Not to Use

- Static layouts with a fixed number of items — use `Grid` or `StackLayout` directly - Map pin lists — use the `Microsoft.Maui.Controls.Maps` NuGet package - Table-based data entry forms — use standard form controls - Simple text-only lists with no interaction — consider `BindableLayout` on a `StackLayout`

## Scope Control — Answer Only What Was Asked

This skill is a **reference you consult**, not a checklist you apply. Most requests need one or two sections from it. Pulling in the rest makes the answer worse.

**Stop conditions — do NOT act when:**

- **The user asked a narrow question.** Answer that question only. Do not append grouping, swipe actions, empty views, snap points, or performance tips that were not asked about. - **The user's existing code already works.** Do not rewrite working markup to match the examples here. Point out a concrete defect; if there is none, say so and answer the question that was asked. - **The change is stylistic.** Renaming, reordering attributes, or restructuring a template that already behaves correctly is churn, not a fix. - **The control isn't `CollectionView`.** `CarouselView`, `BindableLayout`, and `ListView`-in-maintenance code have different rules. Do not rewrite `ListView` code the user did not ask about — but if they ask *which* control to use, or are migrating from Xamarin.Forms, recommend `CollectionView` (see [Migrating from ListView](#migrating-from-listview)). - **The problem is really a binding, DI, or navigation problem** that happens to involve a list — defer to `maui-data-binding`, `maui-dependency-injection`, or `maui-shell-navigation`.

**The API sections below are a reference, not a checklist — offer them only when relevant.** Four rules are non-negotiable, because violating them produces code that does not work or silently loses compile-time checking:

1. Never use `ViewCell` as a `DataTemplate` root in `CollectionView`. 2. Use `ObservableCollection<T>` when the list mutates after first render. 3. Mutate the bound collection on the UI thread. 4. Set `x:DataType` on every `DataTemplate` (and on the page root) for compiled bindings.

Everything else — sizing strategy, snap points, header/footer, empty views — is optional and should be offered only when it addresses the user's actual problem.

## Inputs

- A data source (typically `ObservableCollection<T>`) bound to `ItemsSource` - A `DataTemplate` defining how each item renders - Optional: layout configuration, selection mode, grouping model, empty view

## Basic Setup

A complete, copy-pasteable page. Two things are load-bearing: the `xmlns:models` declaration that every `x:DataType="models:Item"` in this skill assumes, and the **root `x:DataType`** — without it the outer `ItemsSource` binding is not compiled:

```xml <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" xmlns:models="clr-namespace:MyApp.Models" xmlns:vm="clr-namespace:MyApp.ViewModels" x:DataType="vm:ItemsViewModel" x:Class="MyApp.ItemsPage"> <ContentPage.BindingContext> <vm:ItemsViewModel /> </ContentPage.BindingContext> <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <HorizontalStackLayout Padding="8" Spacing="8"> <Image Source="{Binding Icon}" WidthRequest="40" HeightRequest="40" /> <Label Text="{Binding Name}" VerticalOptions="Center" /> </HorizontalStackLayout> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> </ContentPage> ```

Later snippets show only the `CollectionView` element. When you hand a snippet to a user, include the matching `xmlns:` declaration for any prefix it uses, or the XAML will not compile.

The inline `<ContentPage.BindingContext>` above keeps the example self-contained. In an app that uses dependency injection, register the ViewModel instead and assign it through constructor injection (`BindingContext = vm;`) — see the **maui-dependency-injection** skill.

**Key rules:**

- Bind `ItemsSource` to an `ObservableCollection<T>` so the UI updates on add/remove. - Each item template root must be a `Layout` or `View` — **never use `ViewCell`**. - Always set `x:DataType` on `DataTemplate` for compiled bindings.

## Layouts

Set `ItemsLayout` to control arrangement. Default is `VerticalList`.

| Layout | XAML value | |---|---| | Vertical list | `VerticalList` (default) | | Horizontal list | `HorizontalList` | | Vertical grid | `GridItemsLayout` with `Orientation="Vertical"` | | Horizontal grid | `GridItemsLayout` with `Orientation="Horizontal"` |

### Grid Layout

```xml <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemsLayout> <GridItemsLayout Orientation="Vertical" Span="2" VerticalItemSpacing="8" HorizontalItemSpacing="8" /> </CollectionView.ItemsLayout> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Border Padding="8" StrokeThickness="0"> <VerticalStackLayout> <Image Source="{Binding Image}" HeightRequest="120" Aspect="AspectFill" /> <Label Text="{Binding Name}" FontAttributes="Bold" /> </VerticalStackLayout> </Border> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

### Horizontal List

```xml <CollectionView ItemsSource="{Binding Items}" ItemsLayout="HorizontalList" /> ```

## Selection

### Selection Mode

| Mode | Property to bind | Binding mode | |---|---|---| | `None` | — | — | | `Single` | `SelectedItem` | `TwoWay` | | `Multiple` | `SelectedItems` | `OneWay` |

```xml <CollectionView ItemsSource="{Binding Items}" SelectionMode="Single" SelectedItem="{Binding CurrentItem, Mode=TwoWay}" SelectionChangedCommand="{Binding ItemSelectedCommand}" /> ```

For `Multiple` selection, bind `SelectedItems` (type `IList<object>`):

```xml <CollectionView SelectionMode="Multiple" SelectedItems="{Binding ChosenItems, Mode=OneWay}" /> ```

### Selected Visual State

Highlight selected items using `VisualStateManager`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Grid Padding="8"> <VisualStateManager.VisualStateGroups> <VisualStateGroup Name="CommonStates"> <VisualState Name="Normal"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="Transparent" /> </VisualState.Setters> </VisualState> <VisualState Name="Selected"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="{AppThemeBinding Light={StaticResource Primary}, Dark={StaticResource PrimaryDark}}" /> </VisualState.Setters> </VisualState> </VisualStateGroup> </VisualStateManager.VisualStateGroups> <Label Text="{Binding Name}" /> </Grid> </DataTemplate> </CollectionView.ItemTemplate> ```

## Grouping

1. Create a group class inheriting from `List<T>`:

```csharp public class AnimalGroup : List<Animal> { public string Name { get; } public AnimalGroup(string name, List<Animal> animals) : base(animals) { Name = name; } } ```

2. Bind to `ObservableCollection<AnimalGroup>` and set `IsGrouped="True"`:

```xml <CollectionView ItemsSource="{Binding AnimalGroups}" IsGrouped="True"> <CollectionView.GroupHeaderTemplate> <DataTemplate x:DataType="models:AnimalGroup"> <Label Text="{Binding Name}" FontAttributes="Bold" BackgroundColor="{StaticResource Gray100}" Padding="8" /> </DataTemplate> </CollectionView.GroupHeaderTemplate> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Animal"> <Label Text="{Binding Name}" Padding="16,4" /> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

## Pull-to-Refresh

Wrap `CollectionView` in a `RefreshView`. Set `IsRefreshing` back to `false` when done:

```xml <RefreshView IsRefreshing="{Binding IsRefreshing}" Command="{Binding RefreshCommand}"> <CollectionView ItemsSource="{Binding Items}" /> </RefreshView> ```

## Incremental Loading (Infinite Scroll)

```xml <CollectionView ItemsSource="{Binding Items}" RemainingItemsThreshold="5" RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}" /> ```

> ⚠️ **Do NOT use with non-virtualizing layouts.** `LinearItemsLayout` and `GridItemsLayout` support virtualization. Using `BindableLayout` on a `StackLayout` as an alternative to `CollectionView` has no virtualization, which triggers infinite threshold-reached events.

## SwipeView — Binding from Inside DataTemplate

Commands inside a `DataTemplate` can't directly reach your ViewModel. Use `RelativeSource AncestorType`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <SwipeView> <SwipeView.RightItems> <SwipeItems> <SwipeItem Text="Delete" BackgroundColor="Red" Command="{Binding BindingContext.DeleteCommand, Source={RelativeSource AncestorType={x:Type ContentPage}}}" CommandParameter="{Binding}" /> </SwipeItems> </SwipeView.RightItems> <Grid Padding="8"> <Label Text="{Binding Name}" /> </Grid> </SwipeView> </DataTemplate> </CollectionView.ItemTemplate> ```

## EmptyView

Shown when `ItemsSource` is empty or null.

```xml <CollectionView ItemsSource="{Binding SearchResults}" EmptyView="No items found." /> ```

For a custom empty view, wrap in `ContentView`:

```xml <CollectionView ItemsSour

--- name: maui-collectionview description: > Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: "CollectionView", "list view", "grid layout", "data template", "item template", "grouping", "pull to refresh", "incremental loading", "swipe actions", "empty view", "selection mode", "scroll to item", displaying scrollable data, replacing ListView. DO NOT USE FOR: simple static layouts without scrollable data (use Grid or StackLayout), map pin lists (use Microsoft.Maui.Controls.Maps), table-based data entry forms, non-MAUI list controls, CarouselView or BindableLayout questions, platform-specific handler or renderer customization, diagnosing CollectionView bugs in the MAUI framework itself, or general MVVM/binding questions that merely happen to mention a list (use maui-data-binding). license: MIT ---

# CollectionView — .NET MAUI

`CollectionView` is the primary control for displaying scrollable lists and grids of data in .NET MAUI. It replaces `ListView` with better performance, flexible layouts, and no `ViewCell` requirement.

## When to Use

- Displaying a scrollable list or grid of data items - Binding a collection of objects to a templated item layout - Adding selection (single or multiple), grouping, or pull-to-refresh - Implementing infinite scroll / incremental loading - Showing swipe actions on list items - Displaying an empty state when no data is available

## When Not to Use

- Static layouts with a fixed number of items — use `Grid` or `StackLayout` directly - Map pin lists — use the `Microsoft.Maui.Controls.Maps` NuGet package - Table-based data entry forms — use standard form controls - Simple text-only lists with no interaction — consider `BindableLayout` on a `StackLayout`

## Scope Control — Answer Only What Was Asked

This skill is a **reference you consult**, not a checklist you apply. Most requests need one or two sections from it. Pulling in the rest makes the answer worse.

**Stop conditions — do NOT act when:**

- **The user asked a narrow question.** Answer that question only. Do not append grouping, swipe actions, empty views, snap points, or performance tips that were not asked about. - **The user's existing code already works.** Do not rewrite working markup to match the examples here. Point out a concrete defect; if there is none, say so and answer the question that was asked. - **The change is stylistic.** Renaming, reordering attributes, or restructuring a template that already behaves correctly is churn, not a fix. - **The control isn't `CollectionView`.** `CarouselView`, `BindableLayout`, and `ListView`-in-maintenance code have different rules. Do not rewrite `ListView` code the user did not ask about — but if they ask *which* control to use, or are migrating from Xamarin.Forms, recommend `CollectionView` (see [Migrating from ListView](#migrating-from-listview)). - **The problem is really a binding, DI, or navigation problem** that happens to involve a list — defer to `maui-data-binding`, `maui-dependency-injection`, or `maui-shell-navigation`.

**The API sections below are a reference, not a checklist — offer them only when relevant.** Four rules are non-negotiable, because violating them produces code that does not work or silently loses compile-time checking:

1. Never use `ViewCell` as a `DataTemplate` root in `CollectionView`. 2. Use `ObservableCollection<T>` when the list mutates after first render. 3. Mutate the bound collection on the UI thread. 4. Set `x:DataType` on every `DataTemplate` (and on the page root) for compiled bindings.

Everything else — sizing strategy, snap points, header/footer, empty views — is optional and should be offered only when it addresses the user's actual problem.

## Inputs

- A data source (typically `ObservableCollection<T>`) bound to `ItemsSource` - A `DataTemplate` defining how each item renders - Optional: layout configuration, selection mode, grouping model, empty view

## Basic Setup

A complete, copy-pasteable page. Two things are load-bearing: the `xmlns:models` declaration that every `x:DataType="models:Item"` in this skill assumes, and the **root `x:DataType`** — without it the outer `ItemsSource` binding is not compiled:

```xml <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" xmlns:models="clr-namespace:MyApp.Models" xmlns:vm="clr-namespace:MyApp.ViewModels" x:DataType="vm:ItemsViewModel" x:Class="MyApp.ItemsPage"> <ContentPage.BindingContext> <vm:ItemsViewModel /> </ContentPage.BindingContext> <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <HorizontalStackLayout Padding="8" Spacing="8"> <Image Source="{Binding Icon}" WidthRequest="40" HeightRequest="40" /> <Label Text="{Binding Name}" VerticalOptions="Center" /> </HorizontalStackLayout> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> </ContentPage> ```

Later snippets show only the `CollectionView` element. When you hand a snippet to a user, include the matching `xmlns:` declaration for any prefix it uses, or the XAML will not compile.

The inline `<ContentPage.BindingContext>` above keeps the example self-contained. In an app that uses dependency injection, register the ViewModel instead and assign it through constructor injection (`BindingContext = vm;`) — see the **maui-dependency-injection** skill.

**Key rules:**

- Bind `ItemsSource` to an `ObservableCollection<T>` so the UI updates on add/remove. - Each item template root must be a `Layout` or `View` — **never use `ViewCell`**. - Always set `x:DataType` on `DataTemplate` for compiled bindings.

## Layouts

Set `ItemsLayout` to control arrangement. Default is `VerticalList`.

| Layout | XAML value | |---|---| | Vertical list | `VerticalList` (default) | | Horizontal list | `HorizontalList` | | Vertical grid | `GridItemsLayout` with `Orientation="Vertical"` | | Horizontal grid | `GridItemsLayout` with `Orientation="Horizontal"` |

### Grid Layout

```xml <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemsLayout> <GridItemsLayout Orientation="Vertical" Span="2" VerticalItemSpacing="8" HorizontalItemSpacing="8" /> </CollectionView.ItemsLayout> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Border Padding="8" StrokeThickness="0"> <VerticalStackLayout> <Image Source="{Binding Image}" HeightRequest="120" Aspect="AspectFill" /> <Label Text="{Binding Name}" FontAttributes="Bold" /> </VerticalStackLayout> </Border> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

### Horizontal List

```xml <CollectionView ItemsSource="{Binding Items}" ItemsLayout="HorizontalList" /> ```

## Selection

### Selection Mode

| Mode | Property to bind | Binding mode | |---|---|---| | `None` | — | — | | `Single` | `SelectedItem` | `TwoWay` | | `Multiple` | `SelectedItems` | `OneWay` |

```xml <CollectionView ItemsSource="{Binding Items}" SelectionMode="Single" SelectedItem="{Binding CurrentItem, Mode=TwoWay}" SelectionChangedCommand="{Binding ItemSelectedCommand}" /> ```

For `Multiple` selection, bind `SelectedItems` (type `IList<object>`):

```xml <CollectionView SelectionMode="Multiple" SelectedItems="{Binding ChosenItems, Mode=OneWay}" /> ```

### Selected Visual State

Highlight selected items using `VisualStateManager`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Grid Padding="8"> <VisualStateManager.VisualStateGroups> <VisualStateGroup Name="CommonStates"> <VisualState Name="Normal"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="Transparent" /> </VisualState.Setters> </VisualState> <VisualState Name="Selected"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="{AppThemeBinding Light={StaticResource Primary}, Dark={StaticResource PrimaryDark}}" /> </VisualState.Setters> </VisualState> </VisualStateGroup> </VisualStateManager.VisualStateGroups> <Label Text="{Binding Name}" /> </Grid> </DataTemplate> </CollectionView.ItemTemplate> ```

## Grouping

1. Create a group class inheriting from `List<T>`:

```csharp public class AnimalGroup : List<Animal> { public string Name { get; } public AnimalGroup(string name, List<Animal> animals) : base(animals) { Name = name; } } ```

2. Bind to `ObservableCollection<AnimalGroup>` and set `IsGrouped="True"`:

```xml <CollectionView ItemsSource="{Binding AnimalGroups}" IsGrouped="True"> <CollectionView.GroupHeaderTemplate> <DataTemplate x:DataType="models:AnimalGroup"> <Label Text="{Binding Name}" FontAttributes="Bold" BackgroundColor="{StaticResource Gray100}" Padding="8" /> </DataTemplate> </CollectionView.GroupHeaderTemplate> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Animal"> <Label Text="{Binding Name}" Padding="16,4" /> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

## Pull-to-Refresh

Wrap `CollectionView` in a `RefreshView`. Set `IsRefreshing` back to `false` when done:

```xml <RefreshView IsRefreshing="{Binding IsRefreshing}" Command="{Binding RefreshCommand}"> <CollectionView ItemsSource="{Binding Items}" /> </RefreshView> ```

## Incremental Loading (Infinite Scroll)

```xml <CollectionView ItemsSource="{Binding Items}" RemainingItemsThreshold="5" RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}" /> ```

> ⚠️ **Do NOT use with non-virtualizing layouts.** `LinearItemsLayout` and `GridItemsLayout` support virtualization. Using `BindableLayout` on a `StackLayout` as an alternative to `CollectionView` has no virtualization, which triggers infinite threshold-reached events.

## SwipeView — Binding from Inside DataTemplate

Commands inside a `DataTemplate` can't directly reach your ViewModel. Use `RelativeSource AncestorType`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <SwipeView> <SwipeView.RightItems> <SwipeItems> <SwipeItem Text="Delete" BackgroundColor="Red" Command="{Binding BindingContext.DeleteCommand, Source={RelativeSource AncestorType={x:Type ContentPage}}}" CommandParameter="{Binding}" /> </SwipeItems> </SwipeView.RightItems> <Grid Padding="8"> <Label Text="{Binding Name}" /> </Grid> </SwipeView> </DataTemplate> </CollectionView.ItemTemplate> ```

## EmptyView

Shown when `ItemsSource` is empty or null.

```xml <CollectionView ItemsSource="{Binding SearchResults}" EmptyView="No items found." /> ```

For a custom empty view, wrap in `ContentView`:

```xml <CollectionView ItemsSour

--- name: maui-collectionview description: > Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: "CollectionView", "list view", "grid layout", "data template", "item template", "grouping", "pull to refresh", "incremental loading", "swipe actions", "empty view", "selection mode", "scroll to item", displaying scrollable data, replacing ListView. DO NOT USE FOR: simple static layouts without scrollable data (use Grid or StackLayout), map pin lists (use Microsoft.Maui.Controls.Maps), table-based data entry forms, non-MAUI list controls, CarouselView or BindableLayout questions, platform-specific handler or renderer customization, diagnosing CollectionView bugs in the MAUI framework itself, or general MVVM/binding questions that merely happen to mention a list (use maui-data-binding). license: MIT ---

# CollectionView — .NET MAUI

`CollectionView` is the primary control for displaying scrollable lists and grids of data in .NET MAUI. It replaces `ListView` with better performance, flexible layouts, and no `ViewCell` requirement.

## When to Use

- Displaying a scrollable list or grid of data items - Binding a collection of objects to a templated item layout - Adding selection (single or multiple), grouping, or pull-to-refresh - Implementing infinite scroll / incremental loading - Showing swipe actions on list items - Displaying an empty state when no data is available

## When Not to Use

- Static layouts with a fixed number of items — use `Grid` or `StackLayout` directly - Map pin lists — use the `Microsoft.Maui.Controls.Maps` NuGet package - Table-based data entry forms — use standard form controls - Simple text-only lists with no interaction — consider `BindableLayout` on a `StackLayout`

## Scope Control — Answer Only What Was Asked

This skill is a **reference you consult**, not a checklist you apply. Most requests need one or two sections from it. Pulling in the rest makes the answer worse.

**Stop conditions — do NOT act when:**

- **The user asked a narrow question.** Answer that question only. Do not append grouping, swipe actions, empty views, snap points, or performance tips that were not asked about. - **The user's existing code already works.** Do not rewrite working markup to match the examples here. Point out a concrete defect; if there is none, say so and answer the question that was asked. - **The change is stylistic.** Renaming, reordering attributes, or restructuring a template that already behaves correctly is churn, not a fix. - **The control isn't `CollectionView`.** `CarouselView`, `BindableLayout`, and `ListView`-in-maintenance code have different rules. Do not rewrite `ListView` code the user did not ask about — but if they ask *which* control to use, or are migrating from Xamarin.Forms, recommend `CollectionView` (see [Migrating from ListView](#migrating-from-listview)). - **The problem is really a binding, DI, or navigation problem** that happens to involve a list — defer to `maui-data-binding`, `maui-dependency-injection`, or `maui-shell-navigation`.

**The API sections below are a reference, not a checklist — offer them only when relevant.** Four rules are non-negotiable, because violating them produces code that does not work or silently loses compile-time checking:

1. Never use `ViewCell` as a `DataTemplate` root in `CollectionView`. 2. Use `ObservableCollection<T>` when the list mutates after first render. 3. Mutate the bound collection on the UI thread. 4. Set `x:DataType` on every `DataTemplate` (and on the page root) for compiled bindings.

Everything else — sizing strategy, snap points, header/footer, empty views — is optional and should be offered only when it addresses the user's actual problem.

## Inputs

- A data source (typically `ObservableCollection<T>`) bound to `ItemsSource` - A `DataTemplate` defining how each item renders - Optional: layout configuration, selection mode, grouping model, empty view

## Basic Setup

A complete, copy-pasteable page. Two things are load-bearing: the `xmlns:models` declaration that every `x:DataType="models:Item"` in this skill assumes, and the **root `x:DataType`** — without it the outer `ItemsSource` binding is not compiled:

```xml <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" xmlns:models="clr-namespace:MyApp.Models" xmlns:vm="clr-namespace:MyApp.ViewModels" x:DataType="vm:ItemsViewModel" x:Class="MyApp.ItemsPage"> <ContentPage.BindingContext> <vm:ItemsViewModel /> </ContentPage.BindingContext> <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <HorizontalStackLayout Padding="8" Spacing="8"> <Image Source="{Binding Icon}" WidthRequest="40" HeightRequest="40" /> <Label Text="{Binding Name}" VerticalOptions="Center" /> </HorizontalStackLayout> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> </ContentPage> ```

Later snippets show only the `CollectionView` element. When you hand a snippet to a user, include the matching `xmlns:` declaration for any prefix it uses, or the XAML will not compile.

The inline `<ContentPage.BindingContext>` above keeps the example self-contained. In an app that uses dependency injection, register the ViewModel instead and assign it through constructor injection (`BindingContext = vm;`) — see the **maui-dependency-injection** skill.

**Key rules:**

- Bind `ItemsSource` to an `ObservableCollection<T>` so the UI updates on add/remove. - Each item template root must be a `Layout` or `View` — **never use `ViewCell`**. - Always set `x:DataType` on `DataTemplate` for compiled bindings.

## Layouts

Set `ItemsLayout` to control arrangement. Default is `VerticalList`.

| Layout | XAML value | |---|---| | Vertical list | `VerticalList` (default) | | Horizontal list | `HorizontalList` | | Vertical grid | `GridItemsLayout` with `Orientation="Vertical"` | | Horizontal grid | `GridItemsLayout` with `Orientation="Horizontal"` |

### Grid Layout

```xml <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemsLayout> <GridItemsLayout Orientation="Vertical" Span="2" VerticalItemSpacing="8" HorizontalItemSpacing="8" /> </CollectionView.ItemsLayout> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Border Padding="8" StrokeThickness="0"> <VerticalStackLayout> <Image Source="{Binding Image}" HeightRequest="120" Aspect="AspectFill" /> <Label Text="{Binding Name}" FontAttributes="Bold" /> </VerticalStackLayout> </Border> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

### Horizontal List

```xml <CollectionView ItemsSource="{Binding Items}" ItemsLayout="HorizontalList" /> ```

## Selection

### Selection Mode

| Mode | Property to bind | Binding mode | |---|---|---| | `None` | — | — | | `Single` | `SelectedItem` | `TwoWay` | | `Multiple` | `SelectedItems` | `OneWay` |

```xml <CollectionView ItemsSource="{Binding Items}" SelectionMode="Single" SelectedItem="{Binding CurrentItem, Mode=TwoWay}" SelectionChangedCommand="{Binding ItemSelectedCommand}" /> ```

For `Multiple` selection, bind `SelectedItems` (type `IList<object>`):

```xml <CollectionView SelectionMode="Multiple" SelectedItems="{Binding ChosenItems, Mode=OneWay}" /> ```

### Selected Visual State

Highlight selected items using `VisualStateManager`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Grid Padding="8"> <VisualStateManager.VisualStateGroups> <VisualStateGroup Name="CommonStates"> <VisualState Name="Normal"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="Transparent" /> </VisualState.Setters> </VisualState> <VisualState Name="Selected"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="{AppThemeBinding Light={StaticResource Primary}, Dark={StaticResource PrimaryDark}}" /> </VisualState.Setters> </VisualState> </VisualStateGroup> </VisualStateManager.VisualStateGroups> <Label Text="{Binding Name}" /> </Grid> </DataTemplate> </CollectionView.ItemTemplate> ```

## Grouping

1. Create a group class inheriting from `List<T>`:

```csharp public class AnimalGroup : List<Animal> { public string Name { get; } public AnimalGroup(string name, List<Animal> animals) : base(animals) { Name = name; } } ```

2. Bind to `ObservableCollection<AnimalGroup>` and set `IsGrouped="True"`:

```xml <CollectionView ItemsSource="{Binding AnimalGroups}" IsGrouped="True"> <CollectionView.GroupHeaderTemplate> <DataTemplate x:DataType="models:AnimalGroup"> <Label Text="{Binding Name}" FontAttributes="Bold" BackgroundColor="{StaticResource Gray100}" Padding="8" /> </DataTemplate> </CollectionView.GroupHeaderTemplate> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Animal"> <Label Text="{Binding Name}" Padding="16,4" /> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

## Pull-to-Refresh

Wrap `CollectionView` in a `RefreshView`. Set `IsRefreshing` back to `false` when done:

```xml <RefreshView IsRefreshing="{Binding IsRefreshing}" Command="{Binding RefreshCommand}"> <CollectionView ItemsSource="{Binding Items}" /> </RefreshView> ```

## Incremental Loading (Infinite Scroll)

```xml <CollectionView ItemsSource="{Binding Items}" RemainingItemsThreshold="5" RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}" /> ```

> ⚠️ **Do NOT use with non-virtualizing layouts.** `LinearItemsLayout` and `GridItemsLayout` support virtualization. Using `BindableLayout` on a `StackLayout` as an alternative to `CollectionView` has no virtualization, which triggers infinite threshold-reached events.

## SwipeView — Binding from Inside DataTemplate

Commands inside a `DataTemplate` can't directly reach your ViewModel. Use `RelativeSource AncestorType`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <SwipeView> <SwipeView.RightItems> <SwipeItems> <SwipeItem Text="Delete" BackgroundColor="Red" Command="{Binding BindingContext.DeleteCommand, Source={RelativeSource AncestorType={x:Type ContentPage}}}" CommandParameter="{Binding}" /> </SwipeItems> </SwipeView.RightItems> <Grid Padding="8"> <Label Text="{Binding Name}" /> </Grid> </SwipeView> </DataTemplate> </CollectionView.ItemTemplate> ```

## EmptyView

Shown when `ItemsSource` is empty or null.

```xml <CollectionView ItemsSource="{Binding SearchResults}" EmptyView="No items found." /> ```

For a custom empty view, wrap in `ContentView`:

```xml <CollectionView ItemsSour

--- name: maui-collectionview description: > Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: "CollectionView", "list view", "grid layout", "data template", "item template", "grouping", "pull to refresh", "incremental loading", "swipe actions", "empty view", "selection mode", "scroll to item", displaying scrollable data, replacing ListView. DO NOT USE FOR: simple static layouts without scrollable data (use Grid or StackLayout), map pin lists (use Microsoft.Maui.Controls.Maps), table-based data entry forms, non-MAUI list controls, CarouselView or BindableLayout questions, platform-specific handler or renderer customization, diagnosing CollectionView bugs in the MAUI framework itself, or general MVVM/binding questions that merely happen to mention a list (use maui-data-binding). license: MIT ---

# CollectionView — .NET MAUI

`CollectionView` is the primary control for displaying scrollable lists and grids of data in .NET MAUI. It replaces `ListView` with better performance, flexible layouts, and no `ViewCell` requirement.

## When to Use

- Displaying a scrollable list or grid of data items - Binding a collection of objects to a templated item layout - Adding selection (single or multiple), grouping, or pull-to-refresh - Implementing infinite scroll / incremental loading - Showing swipe actions on list items - Displaying an empty state when no data is available

## When Not to Use

- Static layouts with a fixed number of items — use `Grid` or `StackLayout` directly - Map pin lists — use the `Microsoft.Maui.Controls.Maps` NuGet package - Table-based data entry forms — use standard form controls - Simple text-only lists with no interaction — consider `BindableLayout` on a `StackLayout`

## Scope Control — Answer Only What Was Asked

This skill is a **reference you consult**, not a checklist you apply. Most requests need one or two sections from it. Pulling in the rest makes the answer worse.

**Stop conditions — do NOT act when:**

- **The user asked a narrow question.** Answer that question only. Do not append grouping, swipe actions, empty views, snap points, or performance tips that were not asked about. - **The user's existing code already works.** Do not rewrite working markup to match the examples here. Point out a concrete defect; if there is none, say so and answer the question that was asked. - **The change is stylistic.** Renaming, reordering attributes, or restructuring a template that already behaves correctly is churn, not a fix. - **The control isn't `CollectionView`.** `CarouselView`, `BindableLayout`, and `ListView`-in-maintenance code have different rules. Do not rewrite `ListView` code the user did not ask about — but if they ask *which* control to use, or are migrating from Xamarin.Forms, recommend `CollectionView` (see [Migrating from ListView](#migrating-from-listview)). - **The problem is really a binding, DI, or navigation problem** that happens to involve a list — defer to `maui-data-binding`, `maui-dependency-injection`, or `maui-shell-navigation`.

**The API sections below are a reference, not a checklist — offer them only when relevant.** Four rules are non-negotiable, because violating them produces code that does not work or silently loses compile-time checking:

1. Never use `ViewCell` as a `DataTemplate` root in `CollectionView`. 2. Use `ObservableCollection<T>` when the list mutates after first render. 3. Mutate the bound collection on the UI thread. 4. Set `x:DataType` on every `DataTemplate` (and on the page root) for compiled bindings.

Everything else — sizing strategy, snap points, header/footer, empty views — is optional and should be offered only when it addresses the user's actual problem.

## Inputs

- A data source (typically `ObservableCollection<T>`) bound to `ItemsSource` - A `DataTemplate` defining how each item renders - Optional: layout configuration, selection mode, grouping model, empty view

## Basic Setup

A complete, copy-pasteable page. Two things are load-bearing: the `xmlns:models` declaration that every `x:DataType="models:Item"` in this skill assumes, and the **root `x:DataType`** — without it the outer `ItemsSource` binding is not compiled:

```xml <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" xmlns:models="clr-namespace:MyApp.Models" xmlns:vm="clr-namespace:MyApp.ViewModels" x:DataType="vm:ItemsViewModel" x:Class="MyApp.ItemsPage"> <ContentPage.BindingContext> <vm:ItemsViewModel /> </ContentPage.BindingContext> <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <HorizontalStackLayout Padding="8" Spacing="8"> <Image Source="{Binding Icon}" WidthRequest="40" HeightRequest="40" /> <Label Text="{Binding Name}" VerticalOptions="Center" /> </HorizontalStackLayout> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> </ContentPage> ```

Later snippets show only the `CollectionView` element. When you hand a snippet to a user, include the matching `xmlns:` declaration for any prefix it uses, or the XAML will not compile.

The inline `<ContentPage.BindingContext>` above keeps the example self-contained. In an app that uses dependency injection, register the ViewModel instead and assign it through constructor injection (`BindingContext = vm;`) — see the **maui-dependency-injection** skill.

**Key rules:**

- Bind `ItemsSource` to an `ObservableCollection<T>` so the UI updates on add/remove. - Each item template root must be a `Layout` or `View` — **never use `ViewCell`**. - Always set `x:DataType` on `DataTemplate` for compiled bindings.

## Layouts

Set `ItemsLayout` to control arrangement. Default is `VerticalList`.

| Layout | XAML value | |---|---| | Vertical list | `VerticalList` (default) | | Horizontal list | `HorizontalList` | | Vertical grid | `GridItemsLayout` with `Orientation="Vertical"` | | Horizontal grid | `GridItemsLayout` with `Orientation="Horizontal"` |

### Grid Layout

```xml <CollectionView ItemsSource="{Binding Items}"> <CollectionView.ItemsLayout> <GridItemsLayout Orientation="Vertical" Span="2" VerticalItemSpacing="8" HorizontalItemSpacing="8" /> </CollectionView.ItemsLayout> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Border Padding="8" StrokeThickness="0"> <VerticalStackLayout> <Image Source="{Binding Image}" HeightRequest="120" Aspect="AspectFill" /> <Label Text="{Binding Name}" FontAttributes="Bold" /> </VerticalStackLayout> </Border> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

### Horizontal List

```xml <CollectionView ItemsSource="{Binding Items}" ItemsLayout="HorizontalList" /> ```

## Selection

### Selection Mode

| Mode | Property to bind | Binding mode | |---|---|---| | `None` | — | — | | `Single` | `SelectedItem` | `TwoWay` | | `Multiple` | `SelectedItems` | `OneWay` |

```xml <CollectionView ItemsSource="{Binding Items}" SelectionMode="Single" SelectedItem="{Binding CurrentItem, Mode=TwoWay}" SelectionChangedCommand="{Binding ItemSelectedCommand}" /> ```

For `Multiple` selection, bind `SelectedItems` (type `IList<object>`):

```xml <CollectionView SelectionMode="Multiple" SelectedItems="{Binding ChosenItems, Mode=OneWay}" /> ```

### Selected Visual State

Highlight selected items using `VisualStateManager`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <Grid Padding="8"> <VisualStateManager.VisualStateGroups> <VisualStateGroup Name="CommonStates"> <VisualState Name="Normal"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="Transparent" /> </VisualState.Setters> </VisualState> <VisualState Name="Selected"> <VisualState.Setters> <Setter Property="BackgroundColor" Value="{AppThemeBinding Light={StaticResource Primary}, Dark={StaticResource PrimaryDark}}" /> </VisualState.Setters> </VisualState> </VisualStateGroup> </VisualStateManager.VisualStateGroups> <Label Text="{Binding Name}" /> </Grid> </DataTemplate> </CollectionView.ItemTemplate> ```

## Grouping

1. Create a group class inheriting from `List<T>`:

```csharp public class AnimalGroup : List<Animal> { public string Name { get; } public AnimalGroup(string name, List<Animal> animals) : base(animals) { Name = name; } } ```

2. Bind to `ObservableCollection<AnimalGroup>` and set `IsGrouped="True"`:

```xml <CollectionView ItemsSource="{Binding AnimalGroups}" IsGrouped="True"> <CollectionView.GroupHeaderTemplate> <DataTemplate x:DataType="models:AnimalGroup"> <Label Text="{Binding Name}" FontAttributes="Bold" BackgroundColor="{StaticResource Gray100}" Padding="8" /> </DataTemplate> </CollectionView.GroupHeaderTemplate> <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Animal"> <Label Text="{Binding Name}" Padding="16,4" /> </DataTemplate> </CollectionView.ItemTemplate> </CollectionView> ```

## Pull-to-Refresh

Wrap `CollectionView` in a `RefreshView`. Set `IsRefreshing` back to `false` when done:

```xml <RefreshView IsRefreshing="{Binding IsRefreshing}" Command="{Binding RefreshCommand}"> <CollectionView ItemsSource="{Binding Items}" /> </RefreshView> ```

## Incremental Loading (Infinite Scroll)

```xml <CollectionView ItemsSource="{Binding Items}" RemainingItemsThreshold="5" RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}" /> ```

> ⚠️ **Do NOT use with non-virtualizing layouts.** `LinearItemsLayout` and `GridItemsLayout` support virtualization. Using `BindableLayout` on a `StackLayout` as an alternative to `CollectionView` has no virtualization, which triggers infinite threshold-reached events.

## SwipeView — Binding from Inside DataTemplate

Commands inside a `DataTemplate` can't directly reach your ViewModel. Use `RelativeSource AncestorType`:

```xml <CollectionView.ItemTemplate> <DataTemplate x:DataType="models:Item"> <SwipeView> <SwipeView.RightItems> <SwipeItems> <SwipeItem Text="Delete" BackgroundColor="Red" Command="{Binding BindingContext.DeleteCommand, Source={RelativeSource AncestorType={x:Type ContentPage}}}" CommandParameter="{Binding}" /> </SwipeItems> </SwipeView.RightItems> <Grid Padding="8"> <Label Text="{Binding Name}" /> </Grid> </SwipeView> </DataTemplate> </CollectionView.ItemTemplate> ```

## EmptyView

Shown when `ItemsSource` is empty or null.

```xml <CollectionView ItemsSource="{Binding SearchResults}" EmptyView="No items found." /> ```

For a custom empty view, wrap in `ContentView`:

```xml <CollectionView ItemsSour