Palmy.Maui.PullToRefresh 1.1.0

Palmy.Maui.PullToRefresh

A highly customizable pull-to-refresh control for .NET MAUI that allows developers to replace the default refresh indicator with custom animated views.

Car Demo	Shop Demo	Weather Demo	Tickets Demo

Features

• Custom refresh indicator — use any MAUI View (Lottie animations, images, custom layouts)
• Two display modes: Normal (pushes content down) and Overlay (floats above content)
• Fine-grained pull state tracking via the Pulling event
• Configurable pull distance, refresh height, and animation easing
• MVVM-friendly with bindable RefreshCommand and IsRefreshing properties
• Supports Android and iOS

Installation

dotnet add package Palmy.Maui.PullToRefresh

Quick Start

1. Add the namespace

xmlns:pullToRefresh="clr-namespace:Palmy.Maui.PullToRefresh;assembly=Palmy.Maui.PullToRefresh"

2. Basic usage (Normal mode)

Wrap your scrollable content with PullToRefreshView and provide a custom RefreshView:

<pullToRefresh:PullToRefreshView IsRefreshing="{Binding IsRefreshing}"
                                 RefreshCommand="{Binding RefreshCommand}"
                                 MaxPullDistance="160"
                                 RefreshHeight="80"
                                 Type="Normal">

    
    <pullToRefresh:PullToRefreshView.RefreshView>
        <Border BackgroundColor="#6200EE"
                HeightRequest="80"
                StrokeThickness="0">
            <ActivityIndicator IsRunning="True"
                               Color="White"
                               HorizontalOptions="Center"
                               VerticalOptions="Center" />
        </Border>
    </pullToRefresh:PullToRefreshView.RefreshView>

    
    <ScrollView>
        <VerticalStackLayout Padding="16" Spacing="12">
            <Label Text="Pull down to refresh!" FontSize="18" />
            
        </VerticalStackLayout>
    </ScrollView>

</pullToRefresh:PullToRefreshView>

3. Overlay mode

Use Type="Overlay" to display the refresh indicator floating above your content:

<pullToRefresh:PullToRefreshView IsRefreshing="{Binding IsRefreshing}"
                                 RefreshCommand="{Binding RefreshCommand}"
                                 MaxPullDistance="420"
                                 RefreshHeight="120"
                                 Type="Overlay"
                                 AnimationTransition="{x:Static Easing.CubicInOut}">

    <pullToRefresh:PullToRefreshView.RefreshView>
        <Grid HeightRequest="120" IsClippedToBounds="True">
            <Border Padding="0"
                    BackgroundColor="White"
                    HeightRequest="60"
                    HorizontalOptions="Center"
                    StrokeShape="RoundRectangle 30,30,30,30"
                    StrokeThickness="0"
                    VerticalOptions="Center"
                    WidthRequest="60">
                <ActivityIndicator IsRunning="True"
                                   Color="#6200EE"
                                   HeightRequest="40"
                                   WidthRequest="40" />
            </Border>
        </Grid>
    </pullToRefresh:PullToRefreshView.RefreshView>

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

</pullToRefresh:PullToRefreshView>

4. LoadingView — full-screen loading overlay

Use LoadingView to display a full-area view while data is being fetched. It fades in automatically when the refresh starts and fades out when IsRefreshing returns to false:

<pullToRefresh:PullToRefreshView IsRefreshing="{Binding IsRefreshing}"
                                 RefreshCommand="{Binding RefreshCommand}"
                                 MaxPullDistance="500"
                                 RefreshHeight="150"
                                 Type="Overlay">

    <pullToRefresh:PullToRefreshView.LoadingView>
        <Grid BackgroundColor="#CC000000">
            <ActivityIndicator IsRunning="True"
                               Color="White"
                               HorizontalOptions="Center"
                               VerticalOptions="Center" />
        </Grid>
    </pullToRefresh:PullToRefreshView.LoadingView>

    <pullToRefresh:PullToRefreshView.RefreshView>
        
    </pullToRefresh:PullToRefreshView.RefreshView>

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

</pullToRefresh:PullToRefreshView>

LoadingView works with both Normal and Overlay strategies. When set, the RefreshView hides and the LoadingView fades in simultaneously as soon as the user releases.

5. ViewModel

public class MyViewModel : INotifyPropertyChanged
{
    private bool _isRefreshing;

    public bool IsRefreshing
    {
        get => _isRefreshing;
        set { _isRefreshing = value; OnPropertyChanged(); }
    }

    public ICommand RefreshCommand { get; }

    public MyViewModel()
    {
        RefreshCommand = new Command(async () => await OnRefreshAsync());
    }

    private async Task OnRefreshAsync()
    {
        IsRefreshing = true;

        // Load your data
        await Task.Delay(2000);

        IsRefreshing = false;
    }

    public event PropertyChangedEventHandler? PropertyChanged;
    protected void OnPropertyChanged([CallerMemberName] string? name = null)
        => PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
}

6. Handling pull states with the Pulling event

Subscribe to Pulling to react to each phase of the gesture — useful for driving custom animations:

<pullToRefresh:PullToRefreshView Pulling="OnPulling" ...>

private void OnPulling(object sender, PullToRefreshEventArgs e)
{
    switch (e.State)
    {
        case PullToRefreshState.Pulling:
            // User is dragging — e.Progress tracks how far (0–100+)
            AnimationView.Progress = (float)e.Progress / 100;
            break;
        case PullToRefreshState.ReleaseToRefresh:
            // Passed the threshold — user can release to trigger refresh
            break;
        case PullToRefreshState.Refreshing:
            // Refresh started — play a looping animation
            AnimationView.Play();
            break;
        case PullToRefreshState.Finished:
        case PullToRefreshState.Canceled:
            // Done or canceled — stop animation
            AnimationView.Stop();
            break;
    }
}

API Reference

PullToRefreshState values

Platforms

License

MIT