RefreshView

Browse the sample

The .NET Multi-platform App UI (.NET MAUI) RefreshView is a container control that provides pull to refresh functionality for scrollable content. Therefore, the child of a RefreshView must be a scrollable control, such as ScrollView, CollectionView, or ListView.

RefreshView defines the following properties:

• Command, of type ICommand, which is executed when a refresh is triggered.
• CommandParameter, of type object, which is the parameter that's passed to the Command.
• IsRefreshEnabled, of type bool, which indicates whether pull to refresh is enabled.
• IsRefreshing, of type bool, which indicates the current state of the RefreshView.
• RefreshColor, of type Color, the color of the progress circle that appears during the refresh.

These properties are backed by BindableProperty objects, which means that they can be targets of data bindings, and styled.

Note

On Windows, the pull direction of a RefreshView can be set with a platform-specific property. For more information, see RefreshView pull direction on Windows.

Create a RefreshView

To add a RefreshView to a page, create a RefreshView object and set its IsRefreshing and Command properties. Then set its child to a scrollable control.

The following example shows how to instantiate a RefreshView in XAML:

<ContentPage ...
             xmlns:local="clr-namespace:RefreshViewDemo"
             x:DataType="local:MainPageViewModel">
    <ContentPage.BindingContext>
        <local:MainPageViewModel />
    </ContentPage.BindingContext>             
    <RefreshView IsRefreshing="{Binding IsRefreshing}"
                 Command="{Binding RefreshCommand}">
        <ScrollView>
            <FlexLayout Direction="Row"
                        Wrap="Wrap"
                        AlignItems="Center"
                        AlignContent="Center"
                        BindableLayout.ItemsSource="{Binding Items}"
                        BindableLayout.ItemTemplate="{StaticResource ColorItemTemplate}" />
        </ScrollView>
    </RefreshView>
</ContentPage>

A RefreshView can also be created in code:

RefreshView refreshView = new RefreshView();
ICommand refreshCommand = new Command(() =>
{
    // IsRefreshing is true
    // Refresh data here
    refreshView.IsRefreshing = false;
});
refreshView.Command = refreshCommand;

ScrollView scrollView = new ScrollView();
FlexLayout flexLayout = new FlexLayout { ... };
scrollView.Content = flexLayout;
refreshView.Content = scrollView;

In this example, the RefreshView provides pull to refresh functionality to a ScrollView whose child is a FlexLayout. The FlexLayout uses a bindable layout to generate its content by binding to a collection of items, and sets the appearance of each item with a DataTemplate. For more information about bindable layouts, see Bindable layout.

The value of the RefreshView.IsRefreshing property indicates the current state of the RefreshView. When a refresh is triggered by the user, this property will automatically transition to true. Once the refresh completes, you should reset the property to false.

When the user initiates a refresh, the ICommand defined by the Command property is executed, which should refresh the items being displayed. A refresh visualization is shown while the refresh occurs, which consists of an animated progress circle. The following screenshot shows the progress circle on iOS:

Note

Manually setting the IsRefreshing property to true will trigger the refresh visualization, and will execute the ICommand defined by the Command property.

RefreshView appearance

In addition to the properties that RefreshView inherits from the VisualElement class, RefreshView also defines the RefreshColor property. This property can be set to define the color of the progress circle that appears during the refresh:

<RefreshView RefreshColor="Teal"
             ... />

The following Android screenshot shows a RefreshView with the RefreshColor property:

In addition, the BackgroundColor property can be set to a Color that represents the background color of the progress circle.

Note

On iOS, the BackgroundColor property sets the background color of the UIView that contains the progress circle.

Disable a RefreshView

An app may enter a state where pull to refresh is not a valid operation. Choose the option that matches the behavior you want.

Use IsRefreshEnabled to disable only pull to refresh

IsRefreshEnabled disables the pull to refresh gesture while keeping child content interactive:

<RefreshView IsRefreshEnabled="{Binding CanRefresh}"
             Command="{Binding RefreshCommand}">
    <!-- Login form remains usable -->
    <ScrollView>
        <StackLayout>
            <Entry Placeholder="Username" />
            <Entry Placeholder="Password" IsPassword="true" />
            <Button Text="Login" />
        </StackLayout>
    </ScrollView>
</RefreshView>

Use IsEnabled to disable the entire control

IsEnabled disables the RefreshView and all child content:

<RefreshView IsEnabled="false"
             Command="{Binding RefreshCommand}">
    <!-- Login form will be unusable when IsEnabled is false -->
    <ScrollView>
        <StackLayout>
            <Entry Placeholder="Username" />
            <Entry Placeholder="Password" IsPassword="true" />
            <Button Text="Login" />
        </StackLayout>
    </ScrollView>
</RefreshView>

Use Command.CanExecute to control command execution and pull to refresh

When defining the Command property, the CanExecute delegate of the ICommand can enable or disable command execution:

In .NET 10 and later, Command.CanExecute also contributes to the effective IsRefreshEnabled value. Therefore, when CanExecute returns false, the pull to refresh gesture is disabled (even if IsRefreshEnabled is true).

bool canRefresh = true;

RefreshView refreshView = new RefreshView();
Command refreshCommand = new Command(
    execute: () =>
    {
        // Refresh data here.
    },
    canExecute: () => canRefresh);

refreshView.Command = refreshCommand;

// Later, disable refresh command execution.
canRefresh = false;
refreshCommand.ChangeCanExecute();