Open-source project
xuelongqy/flutter_easy_refresh avatar
xuelongqy/flutter_easy_refresh

flutter_easy_refresh: the default branch is v3 and the newest tag is v4.0.0

A flutter widget that provides pull-down refresh and pull-up load.

4,074 stars653 forksDartMIT

At a glance

What is it?
A pull-to-refresh widget for Flutter whose current release is gated on a framework-side migration, whose default branch is still the 3.x line, whose nested-scroll wrapper silently promotes a non-clamping header, and which ships eleven agent skills across eight packages pinned to two different API generations.
Who is it for?
Decide which line you are on before you read anything else, because the answer changes the import in your first file. If your app still imports the SDK's material library, the README's own instruction is to stay on the 3.5.1 line from the v3 branch, which is also what the default branch gives you; 4.0.0 is for apps that have already run the framework's widget migration.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 23 days ago.
What is it written in?
Mainly Dart, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • xuelongqy/flutter_easy_refresh4,074 ★ · +5
Star history
Repository2026-09-242026-11-15
xuelongqy/flutter_easy_refresh4.1k4.1k

5 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The default branch is v3, the newest tag is v4.0.0

The single most useful fact in this repository is that the default branch is not where the newest release is. The default branch is `v3`, and the release list starts with v4.0.0, published on 2026-10-03 at 11:50, eight minutes after the last push to the branch at 11:42 the same morning. Below that come v3.5.0 from 2026-03-23 and 3.4.0 from 2024-05-14, the last of them carrying no `v` prefix while the other two do.

The README on that default branch documents the 4.x requirements anyway, under a heading that says so, and its link to the Chinese README points at the v4 branch rather than at the branch you are reading. So a plain clone lands on the 3.x code while the page in front of you describes 4.x, and the version advice inside that page is explicit about who belongs where: apps that have already migrated should use 4.0, and apps still on the SDK's material library should stay on `easy_refresh: ^3.5.1` from the v3 branch until they migrate.

The tag naming is a small thing on its own. Combined with a version-named default branch and a README that links across branches, it means three version references have to be reconciled before you write any code, and nothing in the repository reconciles them for you.

4.0 is a framework migration, not a feature release

The requirements section for 4.x is short and its content is not about this package's features. EasyRefresh 4.x requires Flutter 3.47 or newer, and it uses the standalone `material_ui` and `cupertino_ui` packages rather than the ones shipped inside the Flutter SDK. The sentence that follows is the one to quote to a colleague: 4.0 is for apps that have already migrated, and the migration is performed by the framework with `dart fix --apply --code=migrate_design_widgets`.

So adopting the new major version is not a dependency bump. It is a dependency bump that assumes you have already rewritten your imports, and the package's own example shows the result, importing `package:material_ui/material_ui.dart` alongside `package:easy_refresh/easy_refresh.dart`, with the theme built from a colour scheme seed and `GlobalMaterialLocalizations.delegates` supplied explicitly.

That last detail is the mechanism underneath the migration. Built-in indicators read `Theme` and localisations from `material_ui`, which is why the delegates line is not optional in the example: an indicator that draws from the theme has nothing to draw from if the delegates are missing. For a team on the older line, the cost of staying put is that the 3.x branch does not get the newer work, and the cost of moving is a framework-wide import change.

Eleven skills across eight packages, on two API generations

The package family ships agent skills, and the README describes the distribution in one command:

sh
dart run skills@ get

Run in your own app after adding the relevant dependencies, that command pulls the skills for the packages you depend on. The table then shows the shape of the family. Eight packages, eleven skills. The pagination companion `easy_paging` has one, the core `easy_refresh` has three, covering indicators, nested scroll and general usage, and each of the six style packages, bow, bubbles, halloween, skating, space and squats, has a single usage skill.

The paths are uniform, each skill living at `packages/<package>/skills/<skill>/SKILL.md` inside the package it documents rather than in a shared location, which is what lets one command resolve per dependency.

Two details are worth noting. The skills are written against two different API generations: they follow the 4.x APIs for `easy_refresh` and `easy_paging` and the 2.x APIs for the style packages, so a style package is a separate compatibility line from the core. And the installation and update instructions are delegated to the Dart package skills documentation rather than restated, so the README tells you to fetch them from elsewhere. The top level carries a `skills-lock.json` alongside a `.agents/` directory and an `AGENT_CODEBASE_MAP.md`, so the repository also keeps a written map of itself for agents.

Physics is shared by default, and nesting changes the constructor

The first sample is the shortest one and it hides the important rule. In the default constructor, all scrolling components in the child scope share one physics. The README's follow-up sentence is the escape hatch: if there is scroll nesting, use `EasyRefresh.builder` or set the scope with `ScrollConfiguration`.

The builder form moves the physics into a callback, so the list receives the same object the indicator is watching:

dart
  EasyRefresh.builder(
    onRefresh: () async {
      ....
      return IndicatorResult.success;
    },
    onLoad: () async {
      ....
    },
    childBuilder: (context, physics) {
      return ListView(
        physics: physics,
      );
    },
  );

Note the callback contract in that snippet. The `onRefresh` future returns an `IndicatorResult`, so a builder-style refresh has to say what happened, in this case success, where the default form's `onRefresh` returns nothing and the widget infers the outcome. That is why the two constructors are not interchangeable: the builder trades an explicit result for an explicit physics.

The shared-physics default is the part that bites. Two lists inside one `EasyRefresh` will drag the same overscroll behaviour, which is what the feature list means by letting lists have different scrolling feedback and inertia, and the price of that is choosing a different constructor per nesting situation.

The nested wrapper takes physics away from you

The sixth sample is the densest paragraph in the README and it is all restrictions. `EasyRefresh.nested` is described as the first-class wrapper for Flutter's official `NestedScrollView`: it creates that view, applies NestedScrollView-safe physics, and, when `onRefresh` is set, inserts a `HeaderLocator` as the first outer sliver. You do not pass `physics` on `body`.

Three constraints follow, and the middle one is the dangerous kind. The header must be clamping, and non-clamping headers are promoted. Inner bouncing pull-to-refresh is not supported. And the physics parameter is taken away from you, so the shared-physics escape from the default constructor is not available here at all.

Promotion is the one to watch, because it is silent. A header that overscrolls freely will not be rejected at compile time or produce a warning; it will be replaced with a clamping equivalent, and the visual behaviour you configured will not be the behaviour you get.

Secondary headers are supported on top of that, by wrapping a clamping header in a `SecondaryBuilderHeader` and configuring the secondary trigger offset and a secondary dimension, which the visible text begins to name before it stops.

Two ways to place an indicator, and a controller with two switches

Indicators can be positioned in two ways. The direct form constructs a `Header` and a `Footer` with an `IndicatorPosition`, and the locator style places them as slivers inside a `CustomScrollView` using `HeaderLocator.sliver()` and `FooterLocator.sliver()`. The feature list adds that, combined with listeners, an indicator can be placed in any position, so the position is a starting point rather than a constraint. There is also a refresh that fires when the page starts, with a customisable view.

Driving the widget from code goes through a controller with two boolean switches, `controlFinishRefresh` and `controlFinishLoad`, both set to true in the sample. Those flags decide whether the widget may finish the refresh or load on its own or only react to your calls, and the rest of the API is a matched pair: `finishRefresh()` and `resetFooter()` inside the refresh callback, `finishLoad(IndicatorResult.noMore)` inside the load callback, and `callRefresh()` and `callLoad()` to trigger them without a gesture.

The styles come last and are set per instance, `MaterialHeader()` and `MaterialFooter()`, or globally by assigning `EasyRefresh.defaultHeaderBuilder` and `defaultFooterBuilder`, which the sample does with the classic pair. So the same visual vocabulary is reachable three ways: per widget, globally, or from a card pack elsewhere in the family.

Distribution runs through pub, a hosted demo and an APK

The links at the top of the README cover four channels. The package itself is on pub.dev as `easy_refresh` with its API reference on the same site, the online demo is hosted on GitHub Pages, the release page carries an APK, and there is a Chinese README linked from the English one.

The APK is the item that says something about the project. A Flutter widget library does not usually need to publish a binary, so the releases are carrying a build of the example application, and the example directory in the tree is a full multi-platform app with folders for Android, iOS, macOS, web and Windows, plus its own analysis options, assets, resources and tests. That is the artefact the APK comes from, and it is also the reason the demo link is a hosted page rather than a screenshot.

The rest of the top level is small and conventional: a workspace `pubspec.yaml` with its lockfile, the `packages/` directory holding the eight packages, `CHANGELOG.md`, the licence, and a `.github/` directory. What is not conventional is the pair of agent-facing files already mentioned, a `skills-lock.json` recording the fetched skills and an `AGENT_CODEBASE_MAP.md` describing the codebase, both of which are maintained alongside the code rather than generated from it.

Editorial conclusion

Decide which line you are on before you read anything else, because the answer changes the import in your first file. If your app still imports the SDK's material library, the README's own instruction is to stay on the 3.5.1 line from the v3 branch, which is also what the default branch gives you; 4.0.0 is for apps that have already run the framework's widget migration. Two behaviours to plan for either way. In the default constructor every scrolling child shares one physics object, so nested lists need the builder form or an explicit scroll configuration. And in the nested wrapper the header must be clamping, because a non-clamping one is promoted rather than rejected.

Frequently asked questions

What is flutter_easy_refresh, and which branch should I use?

It is a widget that provides pull-down refresh and pull-up load on Flutter applications, supporting almost all Flutter scrollable widgets, and its function is described as similar to Android's SmartRefreshLayout. The default branch is v3 while the newest release is v4.0.0. The README's own guidance is that 4.0 is for apps that have already migrated and that apps still importing the SDK's material library should stay on easy_refresh ^3.5.1 from the v3 branch until they migrate.

What does EasyRefresh 4.0 require?

Flutter 3.47 or newer, and the standalone material_ui and cupertino_ui packages rather than the ones inside the SDK. The migration is done by the framework with dart fix --apply --code=migrate_design_widgets, and built-in indicators read Theme and localisations from material_ui, which is why the example supplies GlobalMaterialLocalizations.delegates explicitly.

How do I use EasyRefresh.nested with a NestedScrollView?

It is the first-class wrapper for Flutter's NestedScrollView. It creates the view, applies NestedScrollView-safe physics, and inserts HeaderLocator as the first outer sliver when onRefresh is set, and you do not pass physics on body. The header must be clamping, since non-clamping headers are promoted, and inner bouncing pull-to-refresh is not supported. Secondary headers are supported by wrapping a clamping header in SecondaryBuilderHeader and configuring the secondary trigger offset and dimension.

How do I trigger or finish an EasyRefresh from code?

Pass an EasyRefreshController with controlFinishRefresh and controlFinishLoad set, then call finishRefresh() and resetFooter() from the refresh callback and finishLoad with an IndicatorResult such as noMore from the load callback. callRefresh() and callLoad() trigger the same operations without a gesture. Indicators can also be positioned as slivers inside a CustomScrollView with HeaderLocator.sliver() and FooterLocator.sliver(), or set globally through the default header and footer builders.

What agent skills does flutter_easy_refresh ship?

All eight packages in the family ship consumer skills, fetched in your own app with dart run skills@ get after adding the dependencies. The pagination package easy_paging has one skill, the core easy_refresh has three covering indicators, nested scroll and usage, and each of the six style packages has a single usage skill. The skills follow the 4.x APIs for the two core packages and the 2.x APIs for the style packages, and installation and updates are documented on the Dart package skills site.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. xuelongqy/flutter_easy_refresh on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/xuelongqy-flutter-easy-refresh.svg)](https://hysenlabs.com/projects/xuelongqy-flutter-easy-refresh)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/xuelongqy-flutter-easy-refresh.svg)](https://hysenlabs.com/projects/xuelongqy-flutter-easy-refresh)

Was this useful?