infinite_scroll_pagination 1.0.0

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

---

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.

Usage

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

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

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

  @override
  void dispose() {
    _dataSource.dispose();
    super.dispose();
  }
}

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

  @override
  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);
    }).catchError(notifyError);
  }
}

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.

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, nextKey and then call notifyListeners.
2. Use one of the convenience functions to do the above for you: notifyError, notifyNewPage or notifyChange. The last one sets the value of all three properties at once.

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

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 states: first page loading, first page error, subsequent page loadings, subsequent page errors, empty list and completed list. Infinite Scroll Pagination takes care of orchestrating between them, rendering each one and pinging you 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 nextKey by yourself, did you remember to call notifyListeners afterward?