maui-collectionview - SKILL.md Agent Skill

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". DO NOT USE FOR: simple static layouts (use maui-data-binding), map pin lists (use maui-maps), or table-based data entry forms.

CollectionView – .NET MAUI

Use CollectionView for displaying scrollable lists and grids of data. It replaces ListView and offers better performance, flexible layouts, and no ViewCell requirement.

Essential patterns

Basic setup

<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>

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.

SwipeView — binding from inside DataTemplate

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

<SwipeItem Text="Delete"
           BackgroundColor="Red"
           Command="{Binding Source={RelativeSource AncestorType={x:Type viewmodels:MainViewModel}}, Path=DeleteCommand}"
           CommandParameter="{Binding}" />

Pull-to-refresh

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

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

Incremental loading (infinite scroll)

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

⚠️ Do NOT use with StackLayout-based ItemsLayout — it has no virtualization and triggers infinite threshold-reached events. Always use LinearItemsLayout or GridItemsLayout.

Performance tips

Use MeasureFirstItem for uniform item sizes — significantly faster than the default MeasureAllItems:
```
<LinearItemsLayout Orientation="Vertical" ItemSizingStrategy="MeasureFirstItem" />
```
Always use ObservableCollection<T>, not List<T>. Swapping a List forces a full re-render.
Update collections on the UI thread — MainThread.BeginInvokeOnMainThread(() => Items.Add(item)).

Common gotchas

Issue	Fix
UI doesn't update when items change	Use `ObservableCollection<T>`, not `List<T>`.
App crashes or blank items	Never use `ViewCell` — use `Grid`, `StackLayout`, or any `View` as template root.
Items disappear or layout breaks	Always update `ItemsSource` and the collection on the UI thread (`MainThread.BeginInvokeOnMainThread`).
Incremental loading fires endlessly	Don't use `StackLayout` as layout; use `LinearItemsLayout` or `GridItemsLayout`.
EmptyView doesn't render correctly	Wrap custom empty views in `ContentView`.
Poor scroll performance	Use `MeasureFirstItem` sizing strategy for uniform item sizes.
Selected state not visible	Add `VisualState Name="Selected"` to the item template root element.
Binding errors in SwipeView commands	Use `RelativeSource AncestorType` to reach the ViewModel from inside the item template.