flutter_pagination_pro 0.8.0

flutter_pagination_pro: ^0.8.0 copied to clipboard

A lightweight Flutter pagination package.
Infinite scroll, load more, grid, slivers, numbered pages — all in one.

Why This Package? #

Quick Start #

dependencies:
  flutter_pagination_pro: ^0.4.0

4 Lines to Paginated List #

PagedListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => ListTile(title: Text(user.name)),
)

That's it. No initialPageKey, no extra type parameter. Handles loading, errors, empty state, and infinite scroll automatically.

PagedListView<T> is a shorthand for PaginationListView<int, T> with initialPageKey defaulting to 1. Same for PagedGridView<T>, PagedController<T>, SliverPagedList<T>, SliverPagedGrid<T>.

Cursor-Based (e.g. Firestore, GraphQL) #

PaginationListView<String, User>(
  fetchPage: (cursor) => api.getUsers(cursor: cursor),
  initialPageKey: '',
  nextPageKeyBuilder: (_, items) => items.last.cursor,
  itemBuilder: (context, user, index) => ListTile(title: Text(user.name)),
)

All Modes #

// Grid
PagedGridView<Photo>(
  fetchPage: (page) => api.getPhotos(page: page),
  itemBuilder: (context, photo, index) => PhotoCard(photo: photo),
  gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(crossAxisCount: 2),
)

// Load More Button
PagedListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserCard(user: user),
  paginationType: PaginationType.loadMore,
)

// Controlled Mode (BYO state)
PaginationListView<int, User>.controlled(
  items: users,
  status: PaginationStatus.loaded,
  onLoadMore: () => bloc.add(LoadNextPage()),
  itemBuilder: (context, user, index) => UserCard(user: user),
)

// Numbered Pagination
NumberedPagination(
  totalPages: 20,
  currentPage: _page,
  onPageChanged: (page) => setState(() => _page = page),
)

Bidirectional (Two-Way) Pagination #

Load items in both directions — ideal for chat apps, timelines, and log viewers. Uses CustomScrollView(center:) so backward items grow upward without disturbing scroll position.

// Chat-style: start at page 10, load older (backward) and newer (forward)
BidirectionalPagedListView<Message>(
  fetchPage: (page) => api.getMessages(page: page),
  fetchPreviousPage: (page) => api.getOlderMessages(before: page),
  initialPageKey: 10,
  itemBuilder: (context, msg, index) => MessageBubble(msg),
)

With Controller #

final controller = BidirectionalPagedController<Message>(
  fetchPage: (page) => api.getMessages(page: page),
  fetchPreviousPage: (page) => api.getOlderMessages(before: page),
  initialPageKey: 10,
);

BidirectionalPagedListView<Message>.withController(
  controller: controller,
  itemBuilder: (context, msg, index) => MessageBubble(msg),
)

Cursor-Based Bidirectional #

BidirectionalPaginationListView<String, Message>(
  fetchPage: (cursor) => api.getNewerMessages(after: cursor),
  fetchPreviousPage: (cursor) => api.getOlderMessages(before: cursor),
  initialPageKey: latestCursor,
  nextPageKeyBuilder: (_, items) => items.last.cursor,
  previousPageKeyBuilder: (_, items) => items.first.cursor,
  itemBuilder: (context, msg, index) => MessageBubble(msg),
)

Slivers (CustomScrollView) #

CustomScrollView(
  controller: scrollController,
  slivers: [
    SliverAppBar(title: Text('Users'), floating: true),
    SliverPaginatedList<int, User>(
      controller: controller,
      scrollController: scrollController,
      itemBuilder: (context, user, index) => ListTile(title: Text(user.name)),
    ),
  ],
)

SliverPaginatedGrid works the same way — just add a gridDelegate.

Controller #

final controller = PagedController<User>(
  fetchPage: (page) => api.getUsers(page: page),
  config: PaginationConfig(pageSize: 20),  // auto-detects last page
  initialItems: cachedUsers,                // show cached data instantly
);

// Use with widget
PagedListView<User>.withController(
  controller: controller,
  itemBuilder: (context, user, index) => UserTile(user: user),
)

// Search / filter: swap the data source at runtime
controller.updateFetchPage(
  (page) => api.searchUsers(page: page, query: 'john'),
);

Customization #

Override any state widget:

PagedListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  firstPageLoadingBuilder: (context) => MyShimmer(),
  firstPageErrorBuilder: (context, error, retry) => MyErrorWidget(error, retry),
  emptyBuilder: (context) => MyEmptyState(),
  loadMoreLoadingBuilder: (context) => MyLoadingSpinner(),
  loadMoreErrorBuilder: (context, error, retry) => MyRetryBar(error, retry),
  endOfListBuilder: (context) => Text('All caught up!'),
  enablePullToRefresh: true,
  separatorBuilder: (context, index) => Divider(),
)

Header & Footer #

Add a header or footer that scrolls with the items — no need to switch to CustomScrollView yourself:

PagedListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  header: Padding(
    padding: EdgeInsets.all(16),
    child: Text('All Users', style: TextStyle(fontSize: 24)),
  ),
  footer: Center(child: Text('End of list')),
)

Available on both PaginationListView and PaginationGridView (all constructors).

Animated List #

Animate item insertions and removals with AnimatedPaginationListView. New pages slide+fade in with stagger; removed items fade+shrink out.

// Zero-config default animations
AnimatedPagedListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  plainItemBuilder: (context, user, index) => UserTile(user: user),
  staggerDelay: Duration(milliseconds: 50),
)

// Custom animation control
AnimatedPaginationListView<int, User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index, animation) => SizeTransition(
    sizeFactor: animation,
    child: FadeTransition(opacity: animation, child: UserTile(user: user)),
  ),
  removeItemBuilder: (context, user, index, animation) => FadeTransition(
    opacity: animation,
    child: UserTile(user: user),
  ),
)

Works with controller mutations — insertItem(), removeItemAt(), removeWhere() all trigger animations automatically.

Skeleton / Shimmer Loading #

Zero-config (recommended) #

Add placeholderItem to your widget — it reuses your existing itemBuilder with a grey overlay:

PagedListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  placeholderItem: User(name: '', email: ''),  // just add this!
  placeholderCount: 8,                          // optional, default 6
  skeletonOverlayColor: Colors.grey.shade200,   // optional
)

Available on all four widget types: PaginationListView, PaginationGridView, SliverPaginatedList, and SliverPaginatedGrid.

Custom skeleton builder #

For full control, use DefaultFirstPageLoading.builder():

PagedListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  firstPageLoadingBuilder: (context) => DefaultFirstPageLoading.builder(
    itemBuilder: (context, index) => ShimmerUserTile(),
    itemCount: 10,
    separatorBuilder: (context, index) => Divider(height: 1),
  ),
)

Pair with the shimmer package for animated shimmer effects — this package stays lightweight.

Testing Utilities #

Import testing.dart for pre-built test helpers and matchers:

import 'package:flutter_pagination_pro/testing.dart';

final controller = testPaginationController<int, User>(
  items: [user1, user2, user3],
  status: PaginationStatus.loaded,
  currentPageKey: 1,
);

expect(controller, hasItemCount(3));
expect(controller, isOnPage(1));
expect(controller, hasStatus(PaginationStatus.loaded));
expect(controller, isPaginationCompleted);  // status + hasMorePages
expect(controller, hasPaginationError());   // any error status
expect(controller, isPaginationEmpty);      // empty status + no items

Configuration #

PaginationConfig #

Auto-Retry with Exponential Backoff #

Automatically retry failed page loads with configurable backoff:

PaginationListView<int, User>(
  fetchPage: (page) => api.getUsers(page),
  config: PaginationConfig(
    retryPolicy: RetryPolicy(
      maxRetries: 3,
      initialDelay: Duration(seconds: 1),
      backoffMultiplier: 2.0, // 1s → 2s → 4s
    ),
  ),
  itemBuilder: (context, user, index) => UserTile(user: user),
)

Access state.retryCount to show retry progress in your UI.

Keyboard Navigation (Desktop & Web) #

Wrap any paginated list with PaginationKeyboardHandler to add keyboard scrolling:

final scrollController = ScrollController();

PaginationKeyboardHandler(
  scrollController: scrollController,
  onEndReached: controller.loadNextPage,
  child: PagedListView<User>.withController(
    controller: controller,
    scrollController: scrollController,
    itemBuilder: (ctx, user, i) => UserTile(user: user),
  ),
)

NumberedPaginationConfig #

Example #

See the example app for a complete demo with all modes.

License #

MIT — see LICENSE.