infinite_scroll_pagination 1.1.0
infinite_scroll_pagination: ^1.1.0 copied to clipboard

Load and display pages of items as the user scrolls down your screen.

Infinite Scroll Pagination Logo Badge GitHub Build Badge Gitter Badge Effective Dart Badge MIT License Badge Flutter Platform Badge

Infinite Scroll Pagination #

Unopinionated, extensible and highly customizable package to help you lazily load and display small chunks of data as the user scrolls down your screen – known as infinite scrolling pagination, endless scrolling pagination, auto-pagination, lazy loading pagination, progressive loading pagination, etc.

Inspired by the ergonomics of the Flutter API itself.

Example Project

Usage #

class CharacterListView extends StatefulWidget {
  _CharacterListViewState createState() => _CharacterListViewState();

class _CharacterListViewState extends State<CharacterListView> {
  final CharacterListViewDataSource _dataSource = CharacterListViewDataSource();

  Widget build(BuildContext context) => 
      PagedListView<int, CharacterSummary>(
        dataSource: _dataSource,
        builderDelegate: PagedChildBuilderDelegate<CharacterSummary>(
          itemBuilder: (context, item, index) => CharacterListItem(
            character: item,

  void dispose() {

class CharacterListViewDataSource
    extends PagedDataSource<int, CharacterSummary> {
  CharacterListViewDataSource() : super(0);
  static const _pageSize = 20;

  void fetchItems(int pageKey) {
    RemoteApi.getCharacterList(pageKey, _pageSize).then((newItems) {
      final hasFinished = newItems.length < _pageSize;
      final nextPageKey =  hasFinished ? null : (pageKey + newItems.length);
      notifyNewPage(newItems, nextPageKey);

For more usage examples, please take a look at our cookbook or check out the example project.

Features #

  • Architecture-agnostic: Works with any state management approach, from setState to BLoC. Not even Future usage is assumed.

  • Layout-agnostic: Out-of-the-box widgets equivalent to GridView, SliverGrid, ListView and SliverList – including .separated constructors. Not enough? You can easily create a custom layout.

  • API-agnostic: By letting you in complete charge of your API calls, Infinite Scroll Pagination works with any pagination strategy.

  • Highly customizable: You can change everything. Provide your own progress, error and empty list indicators. Too lazy to change? The defaults will cover you.

  • Extensible: Seamless integration with pull-to-refresh, searching, filtering and sorting.

  • Listen to state changes: In addition to displaying widgets that indicate the current status, such as progress and error indicators, you can also use a listener to display dialogs/snackbars/toasts or execute any other action.

How It Works #

Everything lies around the PagedDataSource class. You're expected to subclass it and provide your own implementation for fetchItems. You can do whatever you want in there, from directly calling a remote API to sending an event to a BLoC. Once you have your items or an error, you have two options:

  1. Manually change the values of itemList, error, nextPageKey and then call notifyListeners.
  2. Use one of the convenience functions to do the above for you: notifyError, notifyNewPage or notifyChange.

Then, provide an instance of your PagedDataSource subclass along with an instance of a PagedChildBuilderDelegate to one of our paged widgets and you're done.

API Overview #

API Diagram

Motivation #

Flutter indeed makes our job way easier than other toolkits when talking about infinite scrolling. It's when we combine that with pagination and lazy fetching that things get complicated.

ListView.builder builds your items on demand, but it doesn't help you with fetching them or displaying status indicators.

Your listing has many possible statuses: first page loading, first page error, subsequent page loading, subsequent page error, empty list and completed list. Infinite Scroll Pagination takes care of orchestrating between them, rendering each one and letting you know when more data is needed.

Troubleshooting #

If you're facing a problem using this package, run through the items below and see if it helps:

  • When you successfully fetched your first page, did you remember to initialize your itemList with an empty array before trying to add new items to it? Keep in mind that itemList initial value is null.
  • Did you specify the generic types for the package's classes you're using? For example: PagedListView<int, CharacterSummary>.
  • If you've changed the values of itemList, error and/or nextPageKey by yourself, did you remember to call notifyListeners afterward?
pub points


Load and display pages of items as the user scrolls down your screen.

Repository (GitHub)
View/report issues


API reference






Packages that depend on infinite_scroll_pagination