custom_refresh_indicator 0.9.0
custom_refresh_indicator: ^0.9.0

Flutter Android iOS web

Flutter Widget that make it easy to implement custom refresh indicator.

Flutter Custom Refresh Indicator #

This package provides CustomRefreshIndicator widget that make it easy to implement your own custom refresh indicator. It listens for scroll events from scroll widget passed to child argument and parsing it to data easy for custom refresh indicator implementation. Indicator data is provided by IndicatorController (third argument of builder method). Long story short... thats it!

If there is something that can be improved, fixed or you just have some great idea feel free to open github issue HERE or open a pull request HERE.

If you implemented your own custom refresh indicator with this library and you want it to be mentioned here or provided as an example to the eample app, just open a pull request HERE.

Table of Contents #


  /// Scrollable widget
  child: ListView.separated(
    itemBuilder: (BuildContext context, int index) => const SizedBox(
      height: 100,
    separatorBuilder: (BuildContext context, int index) =>
        const SizedBox(height: 20),
  /// Custom indicator builder function
  builder: (
    BuildContext context,
    Widget child,
    IndicatorController controller,
    ) {
      /// TODO: Implement your own refresh indicator
      return Stack(
        children: <Widget>[
            animation: controller,
            builder: (BuildContext context, _) {
              /// This part will be rebuild on every controller change
              return MyIndicator();
          /// Scrollable widget that was provided as [child] argument
          /// TIP:
          /// You can also wrap [child] with [Transform] widget to also a animate list transform (see example app)
  /// A function that's called when the user has dragged the refresh indicator
  /// far enough to demonstrate that they want the app to refresh.
  /// Should return [Future].
  onRefresh: myAsyncRefreshMethod,

Examples #

Almost all of these examples are available in the example application.

Plane indicator [SOURCE CODE] #


Ice cream indicator [SOURCE CODE] #


Simple indicator made with PositionedIndicatorContainer [SOURCE CODE] #


Envelope indicator #


Emoji indicator [SOURCE CODE] #

You can create any indicator you want!


Indicator with complete state [SOURCE CODE] #


Documentation #

CustomRefreshIndicator widget #

CustomRefreshIndicator widget provides an absolute minimum functionality that allows you to create and set your own custom indicators.

IndicatorController #

Controller state and value changes. #

The best way to understand how the "CustomRefreshIndicator" widget changes its controller data is to see the example 😉. An example is available in the example application.


statevaluevalue descriptionDescription
idle==0.0Value eqals 0.0.No user action.
dragging=<0.0Value is eqal 0.0 or larger but lower than 1.0.User is dragging the indicator.
armed>=1.0Value is larger than 1.0.User dragged the indicator further than the distance declared by extentPercentageToArmed or offsetToArmed. User still keeps the finger on the screen.
loading>=1.0Value decreses from last armed state value in duration of armedToLoadingDuration argument to 1.0.User finished dragging (took his finger off the screen), when state was equal to armed. onRefresh function is called.
hiding<=1.0Value decreses in duration of draggingToIdleDuration or loadingToIdleDuration arguments to 0.0.Indicator is hiding after:
- User ended dragging when indicator was in dragging state.
- Future returned from onRefresh function is resolved.
- Complete state ended.
- User started scrolling through the list.
complete==1.0Value equals 1.0 for duration of completeStateDuration argument.This state is OPTIONAL, provide completeStateDuration argument with non null value to enable it.
Loading is completed.

didStateChange #

With this method, you can easily check if the indicator's state has changed.

/// When the state changes to [idle]
if(controller.didStateChange(to: IndicatorState.idle)) {
  // Code...

/// When the state changes from [idle] to [dragging]
if (controller.didStateChange(
  from: IndicatorState.idle,
  to: IndicatorState.dragging,
)) {
  // Code...

/// When the state changes from [idle] to another.
if (controller.didStateChange(
  from: IndicatorState.idle,
)) {
  // Code...

/// When the state changes.
if (controller.didStateChange()) {
  // Code...
pub points


Flutter Widget that make it easy to implement custom refresh indicator.

Repository (GitHub)
View/report issues


API reference






Packages that depend on custom_refresh_indicator