infinite_scroll_pagination

5.1.1

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

Readme

Infinite Scroll Pagination

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

Designed to feel like part of the Flutter framework.

Tutorial

By raywenderlich.com (step-by-step, hands-on, in-depth, and illustrated).

Usage

class ListViewScreen extends StatefulWidget {
  const ListViewScreen({super.key});

  @override
  State<ListViewScreen> createState() => _ListViewScreenState();
}

class _ListViewScreenState extends State<ListViewScreen> {
  late final _pagingController = PagingController<int, Photo>(
    getNextPageKey: (state) => state.lastPageIsEmpty ? null : state.nextIntPageKey,
    fetchPage: (pageKey) => RemoteApi.getPhotos(pageKey),
  );

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

  @override
  Widget build(BuildContext context) => PagingListener(
    controller: _pagingController,
    builder: (context, state, fetchNextPage) => PagedListView<int, Photo>(
      state: state,
      fetchNextPage: fetchNextPage,
      builderDelegate: PagedChildBuilderDelegate(
        itemBuilder: (context, item, index) => ImageListTile(item: item),
      ),
    ),
  );
}

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 corresponding 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 to inform 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.

Migration

if you are upgrading the package, please check the migration guide for instructions on how to update your code.

API Overview

Changelog

5.1.1 - 2025-08-28

Changed

Update example widget usage

Fixed

Null check error in pagedlayoutbuilder
Bloc example state equality
Paging state hash code

5.1.0 - 2025-06-18

Added

nextIntPageKey convenience getter for int pages starting at 1
lastPageIsEmpty convenience getter for APIs which return empty pages when no more data is available
flutter bloc example

Changed

Updated migration guide on how to handle final page

Fixed

disposing PagingController cancels fetch

5.0.0 - 2025-02-24

Added

PagingListener widget to connect a PagingController to a PagedLayoutBuilder.

Changed

PagingController no longer has addPageRequestListener method and firstPageKey parameter. Use the fetchPage parameter of the constructor instead.
PagingController no longer has the itemList, error, and nextPageKey getters and setters. All values are now stored in PagingState.
PagingController no longer has the appendPage and appendLastPage methods. Use the copyWith method of PagingState to update its pages, keys, and hasNextPage fields.
PagingController no longer has the retryLastFailedRequest method. You can simply call fetchNextPage to try again.
PagingController no longer has the invisibleItemsThreshold field. It is now configured in PagedChildBuilderDelegate.
PagingController now features getters matching the fields of PagingState as well as mapItems to modify the items.
PagedLayoutBuilder no longer accepts pagingController as a parameter. It now takes PagingState and fetchNextPage instead.
PagingState now uses pages (List<List<ItemType>>) instead of itemList (List<ItemType>). A new extension getter items is provided for flattening.
PagingState now features keys, a list storing all fetched keys, and hasNextPage replacing nextPageKey.
PagingState now includes isLoading, which tracks whether a request is in progress.
PagingState now provides error as type Object? instead of dynamic.
PagingState now includes mapItems and filterItems extension methods for modifying items conveniently.

Fixed

PagingController now deduplicates requests.
PagingController refresh operations now cancel previous requests.
Off-by-one error in invisibleItemsThreshold calculation.
Failure to trigger page request when invisibleItemsThreshold is too large.
Animating between states with animateTransitions.

4.1.0 - 2024-11-09

Added

PagedSliverMasonryGrid.

Changed

Updates example.

Removed

pubspec.lock from version control.

4.0.0 - 2023-08-17

Added

PagedMasonryGridView.
PagedPageView.
Support for the box protocol in PagedLayoutBuilder.

Changed

Renames PagedSliverBuilder to PagedLayoutBuilder.

3.2.0 - 2022-05-23

Changed

Migrates to Flutter 3.

3.1.0 - 2021-07-04

Added

animated status transitions.

3.0.1+1 - 2021-05-23

Added

Flutter Favorite status to the README.

3.0.1 - 2021-03-08

Added

New unit tests.

Changed

Updates sliver_tools dependency.

Fixed

Code formatting in ListenableListener.

3.0.0 - 2021-03-04

Changed

Promotes null safety to stable release.
Migrates example project to null safety.
Migrates code samples to null safety.

3.0.0-nullsafety.0 - 2021-02-06

Changed

Migrates to null safety.

2.3.0 - 2021-01-15

Added

alternative constructor to PagingController receiving an initial PagingState.

Changed

Cookbook file name.
LICENSE file.

2.2.4 - 2021-01-08

Fixed

New page requests happening before the end of the current frame.

2.2.3 - 2020-12-14

Fixed

Bug in which manually resetting to a previous page would stop requesting subsequent pages.

2.2.2 - 2020-11-04

Added

Condition to avoid requesting the first page when there are preloaded items.

2.2.1 - 2020-10-21

Added

shrinkWrapFirstPageIndicators property to PagedSliverList, PagedSliverGrid, and PagedSliverBuilder.

Changed

Improve error message displayed when calling a disposed PagingController.

Fixed

Separator being displayed on completed lists.

2.2.0+1 - 2020-10-19

Changed

Constraints the Flutter SDK dependency to a minimum version of 1.22.0.

2.2.0 - 2020-10-18

Added

New constructor parameters from ScrollView to PagedListView and PagedGridView.

2.1.0+1 - 2020-10-13

Added

Link to raywenderlich.com tutorial.

Changed

Examples to async/await.

2.1.0 - 2020-10-10

Added

noMoreItemsIndicatorBuilder to PagedChildBuilderDelegate.
Properties to both grid widgets to let you choose whether to display the progress, error, and completed listing indicators as grid items or below the grid, as in the list widgets.

2.0.1 - 2020-10-03

Fixed

PagingController not calling its status listeners.

2.0.0 - 2020-10-02

Changed

BREAKING CHANGE: Replaces PagedDataSource and PagedStateChangeListener with PagingController, favoring composition over inheritance.

1.1.1 - 2020-09-23

Removed

Scroll from first page progress indicator, first page error indicator, and no items found indicator.

1.1.0 - 2020-09-18

Added

PagedStateChangeListener.

1.0.0+2 - 2020-08-22

Added

Documentation to PagedDataSource properties.

Changed

README images reference URL.

1.0.0+1 - 2020-08-22

Added

Images to README.md.
Initial release.

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add infinite_scroll_pagination

pubspec.yaml

name: infinite_scroll_pagination
description: Lazily load and display pages of items as the user scrolls down your screen.
version: 5.1.1
homepage: https://github.com/EdsonBueno/infinite_scroll_pagination

environment:
  sdk: ">=3.4.0 <4.0.0"
  flutter: ">=3.0.0"

dependencies:
  flutter:
    sdk: flutter
  flutter_staggered_grid_view: ^0.7.0
  sliver_tools: ^0.2.12
  collection: ">=1.15.0 <2.0.0"
  meta: ">=1.8.0 <2.0.0"

dev_dependencies:
  flutter_test:
    sdk: flutter

  flutter_lints: ^3.0.1
  mockito: ^5.0.9
  test: ^1.16.5

Version history

Version	Published	Archive	SHA-256
1.0.0	2020-08-22On demand	Download	`99dd5eac…5f0a57`
1.0.0+1	2020-08-22On demand	Download	`3d8fdbb8…c46f88`
1.0.0+2	2020-08-22On demand	Download	`21012eb3…6dc78e`
1.1.0	2020-09-18On demand	Download	`3e34e8f6…e3c9f2`
1.1.1	2020-09-23On demand	Download	`002ac64b…a823fc`
2.0.0	2020-10-02On demand	Download	`ea7b2385…ad320d`
2.0.1	2020-10-03On demand	Download	`aaeda39d…149ff4`
2.1.0	2020-10-10On demand	Download	`2bfdd7b9…cb7752`
2.1.0+1	2020-10-13On demand	Download	`a4433d8d…021495`
2.2.0	2020-10-18On demand	Download	`f55522a0…1480eb`
2.2.0+1	2020-10-19On demand	Download	`59cf72ed…5f3afb`
2.2.1	2020-10-21On demand	Download	`8100ce7f…7ec526`
2.2.2	2020-11-04On demand	Download	`0253a717…c09fc1`
2.2.3	2020-12-14On demand	Download	`03f1491d…793f51`
2.2.4	2021-01-08On demand	Download	`ccd0e7c4…4dd740`
2.3.0	2021-01-15On demand	Download	`0eda1e01…c25f83`
3.0.0-nullsafety.0	2021-02-06On demand	Download	`92adba66…88412b`
3.0.0	2021-03-04On demand	Download	`620325e5…b1f8a0`
3.0.1	2021-03-08On demand	Download	`8c70b732…b0191d`
3.0.1+1	2021-05-23On demand	Download	`42a336c0…e9a0ce`
3.1.0	2021-07-03On demand	Download	`eedd3098…1250fc`
3.2.0	2022-05-23On demand	Download	`9517328f…6d52db`
4.0.0-dev.1	2022-09-15On demand	Download	`0819315e…6ad15b`
4.0.0	2023-08-14On demand	Download	`b68bce20…a7f16a`
4.1.0	2024-11-09On demand	Download	`4047eb81…a279df`
5.0.0	2025-02-24On demand	Download	`ff5232d9…38b234`
5.1.0	2025-06-18On demand	Download	`9b8f9536…df0cd4`
5.1.1	2025-08-28Cached · Upstream SHA-256 matched	Download	`b0d28e37…6fda78`

Dependencies

collection "\u003e=1.15.0 \u003c2.0.0"

flutter { "sdk": "flutter" }

flutter_staggered_grid_view "^0.7.0"

meta "\u003e=1.8.0 \u003c2.0.0"

sliver_tools "^0.2.12"

Selected archive

5.1.1

b0d28e37cd8f62490ff6aef63f9db93d4c78b7f11b7c6b26f33c69d8476fda78

Cached · Upstream SHA-256 matched

28 published versions