Agile.Maui 1.0.2

<img src="Controls/agile.png" width="118" height="118" align="center" /> Agile.Maui

.NET MAUI component library with native implementations for Android, iOS, macOS Catalyst, and Windows. Every control maps directly to the platform's own scrolling and rendering infrastructure — no WebView, no abstraction layers.

Installation

dotnet add package Agile.Maui

Register in MauiProgram.cs

using Agile.Maui;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseAgileMaui();   // registers all handlers

    return builder.Build();
}

XAML namespace

xmlns:agile="clr-namespace:Agile.Maui;assembly=Agile.Maui"

ImageView

Displays a single image with optional zoom and fullscreen viewer. When EnableFullscreen is true and the user taps the image, a full-screen overlay opens with pinch-to-zoom, double-tap, and single-tap-to-dismiss.

How it works

Image loading in all handlers is fully cancellable: loading a new Source while a previous load is in-flight cancels the previous operation before starting the next.

Properties

Events

XAML examples

URL with CenterCrop and max zoom 6×:

<agile:ImageView
    Source="https://example.com/photo.jpg"
    IsUrl="True"
    AspectMode="CenterCrop"
    MaxZoom="6"
    Placeholder="placeholder"
    HeightRequest="220" />

High-quality fullscreen source:

<agile:ImageView
    Source="https://cdn.example.com/thumb.jpg"
    FullscreenSource="https://cdn.example.com/full.jpg"
    IsUrl="True"
    AspectMode="CenterCrop"
    MaxZoom="8"
    HeightRequest="220" />

Local image with AspectFit:

<agile:ImageView
    Source="my_image"
    IsUrl="False"
    AspectMode="AspectFit"
    MaxZoom="4"
    HeightRequest="180" />

Fullscreen disabled:

<agile:ImageView
    Source="https://example.com/photo.jpg"
    IsUrl="True"
    EnableFullscreen="False"
    Placeholder="placeholder"
    HeightRequest="140" />

Code-behind events:

<agile:ImageView
    Source="{Binding ImageUrl}"
    IsUrl="True"
    ImageLoaded="OnImageLoaded"
    ImageFailed="OnImageFailed"
    HeightRequest="220" />

private void OnImageLoaded(object sender, EventArgs e) { /* image ready */ }
private void OnImageFailed(object sender, EventArgs e) { /* show error UI */ }

MVVM commands:

<agile:ImageView
    Source="{Binding ImageUrl}"
    IsUrl="True"
    ImageLoadedCommand="{Binding OnLoadedCommand}"
    ImageFailedCommand="{Binding OnFailedCommand}"
    HeightRequest="220" />

Local image path conventions

GalleryView

Horizontal image gallery with swipe navigation, page indicator, and a fullscreen viewer that preserves the swipe gesture between pages and adds pinch-to-zoom. Supports ObservableCollection<string> — add or remove items at runtime and the gallery updates automatically.

How it works

Thumbnail download is bounded by ThumbMaxPx: Glide (Android) uses RequestOptions.Override(ThumbMaxPx, ThumbMaxPx) to avoid decoding the full-resolution bitmap into memory.

Properties

Events

XAML examples

URL gallery with indicator:

<agile:GalleryView
    Images="{Binding ImageUrls}"
    IsUrl="True"
    AspectMode="CenterCrop"
    MaxZoom="6"
    ShowIndicator="True"
    Placeholder="placeholder"
    HeightRequest="220" />

Custom indicator colors:

<agile:GalleryView
    Images="{Binding ImageUrls}"
    IsUrl="True"
    ShowIndicator="True"
    IndicatorColor="#FF6200EE"
    IndicatorInactiveColor="#66000000"
    HeightRequest="220" />

Memory-optimized gallery with large image lists:

<agile:GalleryView
    Images="{Binding ImageUrls}"
    IsUrl="True"
    ThumbMaxPx="480"
    AspectMode="CenterCrop"
    HeightRequest="220" />

Local image gallery with AspectFit:

<agile:GalleryView
    Images="{Binding LocalImages}"
    IsUrl="False"
    AspectMode="AspectFit"
    MaxZoom="4"
    ShowIndicator="True"
    HeightRequest="200" />

Two-way index binding with events:

<agile:GalleryView
    Images="{Binding Photos}"
    IsUrl="True"
    SelectedIndex="{Binding CurrentIndex, Mode=TwoWay}"
    SelectionChanged="OnSelectionChanged"
    ShowIndicator="True"
    HeightRequest="240" />

private void OnSelectionChanged(object sender, GalleryIndexChangedEventArgs e)
{
    Console.WriteLine($"Current page: {e.Index}");
}

MVVM:

<agile:GalleryView
    Images="{Binding Photos}"
    IsUrl="True"
    SelectedIndex="{Binding CurrentIndex, Mode=TwoWay}"
    SelectionChangedCommand="{Binding PageChangedCommand}"
    ShowIndicator="True"
    HeightRequest="240" />

Reactive updates with ObservableCollection

var photos = new ObservableCollection<string>
{
    "https://example.com/photo1.jpg",
    "https://example.com/photo2.jpg",
};
GalleryControl.Images = photos;

photos.Add("https://example.com/photo3.jpg"); // gallery updates automatically
photos.RemoveAt(0);                            // and on removal too

VirtualizedCollectionView

High-performance list or grid with native virtualization on all platforms. Renders only the items visible on screen and recycles views as the user scrolls — independent of collection size.

How it works

Android — memory tuning: ItemViewCacheSize and RecycledViewPool sizes are calculated from the device's available RAM at handler connect time, so the pool is larger on high-RAM devices.

iOS — event coalescing: INotifyCollectionChanged events are queued and flushed in a single PerformBatchUpdates call. When a batch exceeds 30 operations, or contains a mix of inserts, deletes, and moves, the handler falls back to ReloadData to avoid index conflicts.

Android — async diffing: When ItemsSource is replaced entirely, DiffUtil.CalculateDiff runs on a background thread pool and is cancelled if a newer update arrives before the diff completes.

Properties

Events

Methods

XAML examples

Simple list with automatic height:

<agile:VirtualizedCollectionView
    ItemsSource="{Binding Items}"
    RemainingItemsThreshold="10"
    RemainingItemsThresholdReached="OnLoadMore">
    <agile:VirtualizedCollectionView.ItemTemplate>
        <DataTemplate>
            <Label Text="{Binding Name}" Padding="16,12" />
        </DataTemplate>
    </agile:VirtualizedCollectionView.ItemTemplate>
</agile:VirtualizedCollectionView>

2-column grid with fixed height (best performance):

<agile:VirtualizedCollectionView
    ItemsSource="{Binding Products}"
    ColumnCount="2"
    ItemHeight="120"
    ItemSpacing="4"
    RemainingItemsThreshold="8"
    RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}">
    <agile:VirtualizedCollectionView.ItemTemplate>
        <DataTemplate x:DataType="local:Product">
            <Grid Padding="8">
                <Label Text="{Binding Name}" />
            </Grid>
        </DataTemplate>
    </agile:VirtualizedCollectionView.ItemTemplate>
</agile:VirtualizedCollectionView>

Dynamic height with estimated size (iOS self-sizing):

<agile:VirtualizedCollectionView
    ItemsSource="{Binding Feed}"
    ItemSizeStrategy="Dynamic"
    ItemHeightRequest="200"
    RemainingItemsThreshold="5"
    RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}">
    <agile:VirtualizedCollectionView.ItemTemplate>
        <DataTemplate x:DataType="local:Post">
            <StackLayout Padding="16,12">
                <Label Text="{Binding Title}" FontSize="16" FontAttributes="Bold" />
                <Label Text="{Binding Body}" />
            </StackLayout>
        </DataTemplate>
    </agile:VirtualizedCollectionView.ItemTemplate>
</agile:VirtualizedCollectionView>

Infinite scroll with scroll monitoring (MVVM):

<agile:VirtualizedCollectionView
    ItemsSource="{Binding Items}"
    ItemHeight="80"
    RemainingItemsThreshold="15"
    RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}"
    ScrolledCommand="{Binding ScrolledCommand}">
    <agile:VirtualizedCollectionView.ItemTemplate>
        <DataTemplate x:DataType="local:MyItem">
            <Label Text="{Binding Title}" Padding="16,12" />
        </DataTemplate>
    </agile:VirtualizedCollectionView.ItemTemplate>
    <agile:VirtualizedCollectionView.EmptyView>
        <Label Text="No items found." HorizontalOptions="Center" VerticalOptions="Center" />
    </agile:VirtualizedCollectionView.EmptyView>
</agile:VirtualizedCollectionView>

Programmatic scroll:

MyList.ScrollTo(index: 50, animated: true);

Reading scroll position:

private void OnScrolled(object sender, VirtualizedScrolledEventArgs e)
{
    Console.WriteLine($"ScrollY: {e.ScrollY:F0} dp");
}

ItemSizeStrategy guide

iOS tip: When using ItemSizeStrategy.Dynamic, set ItemHeightRequest as close to the real average height as possible. UIKit uses this estimate to allocate the initial cell pool. A very small estimate (e.g. 44) causes UIKit to create many extra cells upfront, driving memory usage significantly higher.

Performance tips

• Always set ItemHeight when the template has a predictable height. This lets RecyclerView and UICollectionView skip individual item measurement during scroll, reducing CPU usage and jank.
• Set ItemSizeStrategy = Fixed (the default) unless items genuinely vary in height.
• Use x:DataType in DataTemplate to enable compiled bindings — avoids reflection overhead per item.
• Prefer ObservableCollection over replacing the entire ItemsSource for incremental updates. On Android, incremental changes run DiffUtil which animates and avoids full redraw. On iOS, changes are batched into a single PerformBatchUpdates call.

Enums

ZoomImageAspect

Used by ImageView.AspectMode and GalleryView.AspectMode.

VirtualizedOrientation

Used by VirtualizedCollectionView.Orientation.

ItemSizeStrategy

Used by VirtualizedCollectionView.ItemSizeStrategy.

Requirements

Performance tuning

For a detailed reference on internal cache sizes, layout manager selection, DiffUtil behavior, iOS coalescing thresholds, and memory guidelines for images inside cells, see TUNING.md.

License

MIT © 2025 Micael Otowicz