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.

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.

DataTemplateSelector

Choose templates at runtime based on item properties:

public class ItemTemplateSelector : DataTemplateSelector
{
    public DataTemplate NormalTemplate { get; set; }
    public DataTemplate HighlightTemplate { get; set; }

    protected override DataTemplate OnSelectTemplate(object item, BindableObject container)
    {
        return ((Item)item).IsHighlighted ? HighlightTemplate : NormalTemplate;
    }
}

<CollectionView ItemsSource="{Binding Items}"
                ItemTemplate="{StaticResource MyTemplateSelector}" />

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

<CollectionView ItemsSource="{Binding Items}">
    <CollectionView.ItemsLayout>
        <GridItemsLayout Orientation="Vertical"
                         Span="2"
                         VerticalItemSpacing="8"
                         HorizontalItemSpacing="8" />
    </CollectionView.ItemsLayout>
</CollectionView>

Horizontal list

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

ItemSizingStrategy

Controls how items are measured. Set on ItemsLayout.

Value	Behavior
`MeasureAllItems`	Measures every item individually (default). Accurate but slower for heterogeneous sizes.
`MeasureFirstItem`	Measures only the first item and applies that size to all. Much faster for uniform items.

<CollectionView.ItemsLayout>
    <LinearItemsLayout Orientation="Vertical"
                       ItemSizingStrategy="MeasureFirstItem" />
</CollectionView.ItemsLayout>

ItemSpacing

Use ItemSpacing on LinearItemsLayout or VerticalItemSpacing / HorizontalItemSpacing on GridItemsLayout:

<CollectionView.ItemsLayout>
    <LinearItemsLayout Orientation="Vertical" ItemSpacing="8" />
</CollectionView.ItemsLayout>

Headers and footers

Supports string, view, or templated:

<!-- Simple string -->
<CollectionView Header="My Items" Footer="End of list" />

<!-- Custom view -->
<CollectionView ItemsSource="{Binding Items}">
    <CollectionView.Header>
        <Label Text="Header" FontAttributes="Bold" Padding="8" />
    </CollectionView.Header>
    <CollectionView.Footer>
        <Label Text="Footer" FontAttributes="Italic" Padding="8" />
    </CollectionView.Footer>
</CollectionView>

Use HeaderTemplate / FooterTemplate when headers/footers are data-bound.

Selection

Selection mode

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

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

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

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

Selected visual state

Highlight selected items using VisualStateManager:

<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

Create a group class inheriting from List<T>:

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

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

<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.GroupFooterTemplate>
        <DataTemplate x:DataType="models:AnimalGroup">
            <Label Text="{Binding Count, StringFormat='{0} items'}"
                   FontAttributes="Italic"
                   Padding="4,0" />
        </DataTemplate>
    </CollectionView.GroupFooterTemplate>
    <CollectionView.ItemTemplate>
        <DataTemplate x:DataType="models:Animal">
            <Label Text="{Binding Name}" Padding="16,4" />
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

EmptyView

Shown when ItemsSource is empty or null.

<!-- Simple string -->
<CollectionView EmptyView="No items found." />

<!-- Custom view — wrap in a ContentView -->
<CollectionView ItemsSource="{Binding SearchResults}">
    <CollectionView.EmptyView>
        <ContentView>
            <VerticalStackLayout HorizontalOptions="Center" VerticalOptions="Center">
                <Image Source="empty_state.png" WidthRequest="120" />
                <Label Text="Nothing here yet" HorizontalTextAlignment="Center" />
            </VerticalStackLayout>
        </ContentView>
    </CollectionView.EmptyView>
</CollectionView>

You can also use EmptyViewTemplate with a DataTemplateSelector to swap empty views based on state.

Gotcha: When using a custom view for EmptyView, wrap it in a ContentView to avoid layout issues.

Scrolling

ScrollTo

Programmatically scroll by index or item:

// Scroll to index
collectionView.ScrollTo(index: 10, position: ScrollToPosition.Center, animate: true);

// Scroll to item
collectionView.ScrollTo(item: myItem, position: ScrollToPosition.MakeVisible, animate: true);

ScrollToPosition	Behavior
`MakeVisible`	Scrolls just enough to make the item visible
`Start`	Scrolls item to the start of the viewport
`Center`	Scrolls item to the center of the viewport
`End`	Scrolls item to the end of the viewport

Snap points

Control snap behavior after scrolling:

<CollectionView.ItemsLayout>
    <LinearItemsLayout Orientation="Horizontal"
                       SnapPointsType="MandatorySingle"
                       SnapPointsAlignment="Center" />
</CollectionView.ItemsLayout>

SnapPointsType: None, Mandatory, MandatorySingle
SnapPointsAlignment: Start, Center, End

Incremental loading (infinite scroll)

Load more data as the user scrolls near the end:

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

Or handle the RemainingItemsThresholdReached event in code-behind.

Gotcha: Do not use incremental loading with a StackLayout-based ItemsLayout. A StackLayout has no concept of virtualization and will trigger infinite threshold-reached events. Use the default LinearItemsLayout or GridItemsLayout.

SwipeView integration

Wrap item content in SwipeView for swipe actions:

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

Pull-to-refresh with RefreshView

Wrap CollectionView in a RefreshView:

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

Set IsRefreshing back to false in the view model when the refresh completes.

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 view model from inside the item template.

maui-collectionview