pull_to_refresh 1.5.4

flutter_pulltorefresh #

Intro #

a widget provided to the flutter scroll component drop-down refresh and pull up load.support android and ios. If you are Chinese,click here(中文文档)

Download Demo(Android):


Features #

  • pull up load and pull down refresh
  • It's almost fit for all Scroll witgets,like GridView,ListView...
  • provide global setting of default indicator and property
  • provide some most common indicators
  • Support Android and iOS default ScrollPhysics,the overScroll distance can be controlled,custom spring animate,damping,speed.
  • horizontal and vertical refresh,support reverse ScrollView also(four direction)
  • provide more refreshStyle: Behind,Follow,UnFollow,Front,provide more loadmore style
  • Support twoLevel refresh,implments just like TaoBao twoLevel,Wechat TwoLevel
  • enable link indicator which placing other place,just like Wechat FriendCircle refresh effect

Usage #

add this line to pubspec.yaml

     pull_to_refresh: ^1.5.4

import package

    import 'package:pull_to_refresh/pull_to_refresh.dart';

simple example

  List<String> items = ["1", "2", "3", "4", "5", "6", "7", "8"];
  RefreshController _refreshController =
      RefreshController(initialRefresh: false);

  void _onRefresh() async{
    // monitor network fetch
    await Future.delayed(Duration(milliseconds: 1000));
    // if failed,use refreshFailed()

  void _onLoading() async{
    // monitor network fetch
    await Future.delayed(Duration(milliseconds: 1000));
    // if failed,use loadFailed(),if no data return,use LoadNodata()
    setState(() {


  Widget build(BuildContext context) {
    return Scaffold(
      body: SmartRefresher(
        enablePullDown: true,
        enablePullUp: true,
        header: WaterDropHeader(),
        footer: CustomFooter(
          builder: (BuildContext context,LoadStatus mode){
            Widget body ;
              body =  Text("pull up load");
            else if(mode==LoadStatus.loading){
              body =  CupertinoActivityIndicator();
            else if(mode == LoadStatus.failed){
              body = Text("Load Failed!Click retry!");
              body = Text("No more Data");
            return Container(
              height: 55.0,
              child: Center(child:body),
        controller: _refreshController,
        onRefresh: _onRefresh,
        onLoading: _onLoading,
        child: ListView.builder(
          itemBuilder: (c, i) => Card(child: Center(child: Text(items[i]))),
          itemExtent: 100.0,
          itemCount: items.length,

  // from 1.5.0, it is not necessary to add this line
 // void dispose() {
    // TODO: implement dispose
  //  _refreshController.dispose();
  //  super.dispose();
 // }

The global configuration RefreshConfiguration, which configures all Smart Refresher representations under the subtree, is generally stored at the root of MaterialApp and is similar in usage to ScrollConfiguration. In addition, if one of your SmartRefresher behaves differently from the rest of the world, you can use RefreshConfiguration.copyAncestor() to copy attributes from your ancestor RefreshConfiguration and replace attributes that are not empty.

    // Smart Refresher under the global configuration subtree, here are a few particularly important attributes
         headerBuilder: () => WaterDropHeader(),        // Configure the default header indicator. If you have the same header indicator for each page, you need to set this
         footerBuilder:  () => ClassicFooter(),        // Configure default bottom indicator
         headerTriggerDistance: 80.0,        // header trigger refresh trigger distance
         springDescription:SpringDescription(stiffness: 170, damping: 16, mass: 1.9),         // custom spring back animate,the props meaning see the flutter api
         maxOverScrollExtent :100, //The maximum dragging range of the head. Set this property if a rush out of the view area occurs
         maxUnderScrollExtent:0, // Maximum dragging range at the bottom
         enableScrollWhenRefreshCompleted: true, //This property is incompatible with PageView and TabBarView. If you need TabBarView to slide left and right, you need to set it to true.
         enableLoadingWhenFailed : true, //In the case of load failure, users can still trigger more loads by gesture pull-up.
         hideFooterWhenNotFull: false, // Disable pull-up to load more functionality when Viewport is less than one screen
        child: MaterialApp(

ScreenShots #

Examples #

Stylebasicheader in other placereverse + horizontal
StyletwoLeveluse with other widgetschat
Stylesimple custom header(使用SpinKit)dragableScrollSheet+LoadMoreGif Indicator

Indicator #

各种指示器 #

refresh stylepull up load style

More #

Exist Problems #

  • about NestedScrollView,When you slide down and then slide up quickly, it will return back. The main reason is that NestedScrollView does not consider the problem of cross-border elasticity under bouncingScrollPhysics. Relevant flutter issues: 34316, 33367, 29264. This problem can only wait for flutter to fix this.
  • SmartRefresher does not have refresh injection into ScrollView under the subtree, that is, if you put AnimatedList or RecordableListView in the child is impossible. I have tried many ways to solve this problem and failed. Because of the principle of implementation, I have to append it to the head and tail of slivers. In fact, the problem is not that much of my Component issues, such as AnimatedList, can't be used with AnimatedList and GridView unless I convert AnimatedList to SliverAnimatedList is the solution. At the moment, I have a temporary solution to this problem, but it's a bit cumbersome to rewrite the code inside it and then outside ScrollView. Add SmartRefresher, see my two examples Example 1Example 2
  • As for the problem that active request refresh does not allow users to drag, it is specifically described that when active request refresh list scrolls upwards, the user's dragging gesture should be intercepted to prevent user drag from blocking the operation of request refresh. I know that setCanDrag in Scrollable State can prevent it, but this method does not mean that it can be called at any time, once the call timing is wrong, it will crash.

Thanks #



MIT License

Copyright (c) 2018 Jpeng

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.


1.0.0 #

  • initRelease

1.0.1 #

  • Remove bottomColor

1.0.2 #

  • Add Failed RefreshMode when catch data failed
  • ReMake Default header and footer builder
  • Replace RefreshMode,loadMode to refreshing,loading
  • Replace onModeChange to onRefresh,onLoadMore

1.0.3 #

  • Fix error Props
  • Add interupt Scroll when failure status

1.0.4 #

  • Update README and demo

1.0.5 #

  • Remove headerHeight,footerHeight to get height inital
  • Make footer stay at the bottom of the world forever
  • replace idle to idel(my English mistake)
  • Fix defaultIndictor error Icon display

1.0.6 #

  • Use Material default LoadingBar
  • Add a bool paramter to onOffsetChange to know if pullup or pulldown
  • Fix Bug: when pulled up or pull-down, sizeAnimation and IOS elasticity conflict, resulting in beating.

1.0.7 #

  • Fix Bug1: The use of ListView as a container to cause a fatal error (continuous sliding) when the bottom control is reclaimed, using the SingleChildScrollView instead of preventing the base control from recovering many times from the exception
  • Fix Bug2: When the user continues to call at the same time in the two states of pull-down and drop down, the animation has no callback problem when it enters or fails.

1.0.8 #

  • Reproducing bottom indicator, no more manual drag to load more
  • Control property values change more,Mainly:1.onModeChange => onRefreshChange,onLoadChange, 2.Add enableAutoLoadMore,3.Remove bottomVisiableRange

1.1.0 #

Notice: This version of the code changes much, Api too

  • Transfer state changes to Wrapper of indicator to reduce unnecessary interface refresh.
  • No longer using Refreshmode or LoadMode,replaced int because the state is hard to determine.
  • Now support the ScrollView in the reverse mode
  • The indicators are divided into two categories, loadIndicator and refreshIndicator, and the two support header and footer
  • provided a controller to invoke some essential operations inside.
  • Move triggerDistance,completeTime such props to Config
  • Add ClassicIndicator Convenient construction indicator

1.1.1 #

  • Make triigerDistance be equally vaild for LoadWrapper
  • Add enableOverScroll attribute

1.1.2 #

  • Fix Bug:Refreshing the indicator requires multiple dragging to refresh
  • Fix ClassialIndicator syntax errors and display status when no data is added.

1.1.3 #

  • Fix contentList's item cannot be cached,Remove shrinkWrap,physics limit
  • Fix onOffsetChange callback error,In completion, failure, refresh state is also callback
  • Add unfollowIndicator implement in Demo(Example3)

1.1.4 #

  • Fix enableOverScroll does not work
  • Add default IndicatorBuilder when headerBuilder or footerBuilder is null
  • Fix cannot loading when user loosen gesture and listview enter the rebounding

1.1.5 #

  • Fix problem of offsetChange
  • Fix CustomScrollView didn't work
  • Fix refreshIcon not reference in ClassialIndicator

1.1.6 #

  • Fix Compile error after flutter update

1.2.0 #

  • Fixed the problem that ScrollController was not applied to internal controls
  • Optimize RefreshController
  • RefreshController changed to required now
  • Add feature:reuqestRefresh can jumpTo Bottom or Top
  • Fix problem: Refresh can still be triggered when ScrollView is nested internally
  • Remove rendered twice to get indicator height,replaced by using height attribute in Config
  • change RefreshStatus from int to enum

1.3.0 #

Total #

  • Support reverse ScrollView

  • Remove RefreshConfig,LoadConfig,Move to indicator setting

  • Add isNestWrapped to Compatible NestedScrollView

  • replace headerBuilder,footerBuilder attribute to header,footer

  • Separate header and footer operations:onRefresh and onLoading Callback,RefreshStatus is separated into RefreshStatus.LoadStatus

  • Fix Bug: twice loading (the footer state change before the ui update)

RefreshController #

  • Remove sendBack method,replaced by LoadComplete,RefreshComplete ,RefreshFailed,LoadNoData
  • Separate refresh and load operations
  • Add dispose method for Safety in some situation

Indicator #

  • Use another way to achieve drop-down refresh
  • Add drop-down refresh indicator style(Follow,UnFollow,Behind)
  • Add WaterDropIndicator,CustomIndicator
  • Make Custom Indicator easily

1.3.1 #

  • Add onClick CallBack for LoadIndicator
  • Fix enablepullUp or down invalid
  • Fix error Loading after 1.3.0 updated

1.3.2 #

  • Fix WaterDropHeader some attributes invalid
  • Fix enablePullUp and enablePullDown Dynamic set
  • implements auto hide FooterView when less than one page,no need to set enablePullUp to false
  • improve safety after disposed

1.3.3 #

  • Fixed the request Refresh problem: Sometimes it takes two times to be effective
  • Add child key support
  • Fix Bug:Pull-down triggers need to be pulled down more distances to trigger
  • Add resetNoData to resume footer state to idle

1.3.5 #

  • Add hideWhenNotFull bool to disable auto hide footer when data not enough one page
  • Add one new RefreshStyle:Front(just like RefreshIndicator)
  • Fix a bug: When the head overflows the view area, there is no clipping operation
  • Add material header(two indicator for FrontStyle)
  • Remove enableOverScroll

1.3.6 #

  • Fix NestedScrollView issue in 1.3.5
  • decrease default triggerDistance from 100.0 to 80.0
  • improve dragging scrolling speed of Front Style
  • Add offset attr in Front Style

1.3.7 #

  • Adding an asSlivers constructor can be inserted into slivers as a Sliver
  • Fix FrontStyle cannot support dynamic change enablePullDown
  • Fix FrontStyle cannot enter refresh state when init
  • Optimize indicator internal code to avoid locking widgets
  • Fix iOS click status cannot roll back without ScrollController in child
  • Fix one ignored situation after finish refresh -> completed(not in visual range)

1.3.8 #

  • Temporary fix deadly bug: PrimaryScrollController cannot shared by multiple Indicators

1.3.9 #

  • Avoid inner inject padding by buildSlivers in child(ListView,GridView)
  • Add initialRefresh in RefreshController(when you need to requestRefresh in initState)
  • Fix exception RefreshBouncingPhysics velocity value
  • Add IndicatorConfiguration for build indicator for subtrees SmartRefresher
  • Add SkipCanRefresh,CompleteDuration attr in header
  • Fix trigger more times loading when no data come in and too fast loadComplete
  • remove center,anchor in CustomScrollView to Compatible with old versions

1.4.0 #

  • Fix one serious Bug after 1.3.8 upgrade to 1.3.9:enablePullDown = false throw error

1.4.1 #

  • Remove isNestedWrapped(deprecated from 1.3.8)
  • Add headerInsertIndex attr in SmartRefresher
  • Rename IndicatorConfiguration to RefreshConfiguration
  • Move some attr from Indicator to RefreshConfiguration:offset,skipCanRefresh,triggerDistance,autoLoad,hideWhenNotFull
  • Add decoration for classicIndicator(both header and footer)
  • Add Fade effect for WaterDropHeader when dismiss
  • Simplify reverse operation,Add MaterialClassicHeader,WaterDropMaterialHeader reverse feature

1.4.2 #

  • Improving hideWhenNotFull judgment mechanism
  • Fix triggerDistance error after 1.4.0-1.4.1

1.4.3 #

  • change "child" attr limit type from ScrollView to Widget

1.4.4 #

  • Fix Bug:Multiples ScrollPositions shared one ScrollController,when calling controller.requestRefresh cause refresh together( such as keepAlive Widget )
  • When the user Dragging ScrollView(pull up), disable make it change to loading state
  • Add one new LoadStatus:failed(provide click to retry loading)
  • Fix some defaultIcon:noMoreIcon default Invisible

1.4.5 #

  • Remake FrontStyle implements principle,Make it close to the first three styles,Fix some small problems also: 1.when tap StatusBar,it will trigger refresh instead of scroll to top 2.It seems odd to set aside 100 heights in front of scrollOffset for FrontStyle 3.When hideWhenNotFull = false, dragging to pull down will cause loading together

  • Remake RefreshPhysics,Simpify code,child support physics setting now.

  • ClassicIndicator default refreshingIcon:in iOS use ActivityIndicator,in Android use CircularProgressIndicator

1.4.6 #

  • Add horizontal refresh support
  • Fix 1.4.5 default physics Bug in Android simulation
  • Fix Problem: when enablePullDown or enablePullUp = false,it still can overScroll or underScroll when use ClampingScrollPhysics
  • Add maxOverScrollExtent and maxUnderScrollExtent in RefreshConfiguration

1.4.7 #

new Feature:

  • Add twoLevel refresh feature
  • Add linkHeader to link other place header


  • Remove headerInsertIndex(only first sliver)
  • Fix ignore padding attr when child is BoxScrollView
  • add enableTwoLevel,onTwoLevel attr


  • add enableScrollWhenTwoLevel,closeTwoLevelDistance for twoLevel setting


  • Add refreshToidle, twoLevelComplete new api
  • Add initalRefreshStatus,initalLoadStatus new parameter setting default value


  • remove decoration
  • add outerBuilder replace decoration
  • add other attr for twoLevel

Bug Fix:

  • Fix clicking footer trigger loading when no more state
  • footer indicator shouldn't hide when state in noMore,failed and not full in one page


  • Remove asSliver usage in all indicators(no need to use,only support first sliver)
  • make indicator auto fit boxSize,just like SliverToBoxAdapter

1.4.8 #

  • provide three load more style:ShowAlways,HideAlways,ShowWhenLoading
  • add linkFooter
  • Fix Bug: requestRefresh() interupted when physics =Clamping && offset !=0
  • Fix Bug: When viewport not enough onepage ,pull up will change the state to loading,but not callback onLoading
  • revert change before:SmartRefresher change Stateless,Fix position may be null in some stiuations
  • add enableScrollWhenRefreshCompleted,enableBallisticRefresh,enableLoadingWhenFailed bool in RefreshConfiguration
  • enable footerTriggerdistance pass Negative

1.4.9 #

  • Fix MaterialClassicHeader,WaterDropHeader some err
  • Optimze WaterdropMaterial
  • remove hit top in clamping physics
  • add springDescrition,dragSpeedRatio in RefreshConfiguration
  • fix BehindStyle layoutExtent error

1.5.0 #

  • Fix a Big Bug in FrontStyle:When overScroll(pixels <0.0),it shouldn't be disabled gesture
  • add shouldFollowContentWhenNotFull
  • add support to scrollable widget
  • Fix ignore reverse load more paintOrigin issue
  • change hideFooterWhenNotfull default value to false
  • update header default releaseIcon and footer idle default Icon

1.5.1 #

  • add api docs in code
  • add test to prevent previous bugs as much as possible
  • enableScrollWhenCompleted default value change to false,when header spring back,doesn't allow to scroll by gesture
  • improve enableScrollWhenCompleted safety ,fix trigger disable scroll times error
  • maxScrollExtent should subtract boxExtent when floating(indicator layoutExtent != 0) or not
  • maxOverScrollExtent default change to 30.0 in Android,maxUnderScrollExtent default change to 0.0 in Android
  • Fix footer onClick not working when click near footer edge
  • fix canTwoLevel text showing in other twoLevel state
  • when enablePullDown= false && enableTwoLevel = true,it should add header into Viewport
  • remove reverse in some header indicators,inner auto check direction,no need to pass paramter
  • fix render error in footer when asix = Horizontal & reverse = true

1.5.2 #

  • change maxOverScrollExtent default to 60
  • maxScrollExtent should subtract layoutExtent instead of boxExtent when indicator not floating
  • add SmartRefresher builder constructor for some special use stage
  • when child is not extends scrollView,it should convert height to viewport's height when child's height is infite,such as PageView,emptyWidget with Center,else it will use LayoutBuilder get height
  • header,footer now unlimit the type ,convert to widget,but only sliver widget,Considering the problem of combined indicators
  • CustomHeader,CustomFooter expose inner indicator event
  • resetNoData should only can work when footer indicator is noMore state
  • fix twolevel and refresh prior problem

1.5.3 #

  • add new indicator: BezierCircleHeader
  • change spring default value ,make it fast and smooth
  • fix cast ScrollPosition error with NestedScrollView

1.5.4 #

  • add new RefreshConfiguration constructor "copyAncestor"
  • fix bug 1: when !enablePullDown && !enablePullUp crash error
  • fix bug 2: "pixels" call on null when refresh completed and ready to springback In a very short time and disposed
  • enable "primary" attr working,Avoiding clicking on the status bar to cause scrolling to the top in some stiuation
  • requestRefresh() and requestLoading() change to return a future


demo #

A new Flutter project.

Getting Started #

For help getting started with Flutter, view our online documentation.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  pull_to_refresh: ^1.5.4

2. Install it

You can install packages from the command line:

with Flutter:

$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:pull_to_refresh/pull_to_refresh.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Aug 16, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19
  • Flutter: 1.7.8+hotfix.4


Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Health suggestions

Fix lib/src/smart_refresher.dart. (-1 points)

Analysis of lib/src/smart_refresher.dart reported 2 hints:

line 319 col 25: 'scrollController' is deprecated and shouldn't be used.

line 364 col 25: 'scrollController' is deprecated and shouldn't be used.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.6 1.1.7
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies