Enhanced Paginated View

Overview

A customizable Flutter widget for paginated ListView, GridView, and sliver layouts. It handles loading, error, and empty states, infinite scroll, and pull-to-refresh, so your screens only need to supply data and a builder.

List View	Grid View

Features

Flexible layouts – box-based (ListView/GridView) or sliver-based for use inside a CustomScrollView.
Forward or reverse scrolling – set via direction.
Built-in error handling – error and load-more-error states with retry callbacks.
Customizable loading indicators – separate configs for the initial load and load-more.
Infinite scrolling – automatic load-more as the user scrolls, with a tunable loadMoreThreshold.
Data/config separation – EnhancedDelegate carries data only; EnhancedConfig carries all presentation/behavior options.
State management agnostic – works with BLoC, Riverpod, Provider, or plain setState.
Pull-to-refresh – onRefresh callback with an optional refreshBuilder for a custom indicator, in both scroll directions.
Pagination controller – optional EnhancedPaginationController exposing the current page and isLoadingMore state.

Installation

Add the package to your pubspec.yaml:

dependencies:
  enhanced_paginated_view: ^latest_version

Then import it:

import 'package:enhanced_paginated_view/enhanced_paginated_view.dart';

This also exports the EnhancedBoxBuilder, EnhancedSliverBuilder, and EnhancedRefreshBuilder typedefs, useful if you want to extract a builder/refreshBuilder into its own variable or method.

Usage

EnhancedPaginatedView has two constructors: the default box-based builder, and .slivers for sliver-based layouts. EnhancedDelegate carries only data (listOfData + status); everything about presentation and behavior — physics, header, scroll direction, deduplication, loading/error/empty widgets — lives on a separate EnhancedConfig passed via config:.

Note: The box-based builder renders eagerly inside a SingleChildScrollView (similar to shrinkWrap: true), laying out the whole list up front. For very large lists, prefer EnhancedPaginatedView.slivers, which renders lazily inside a CustomScrollView.

Box-based view

EnhancedPaginatedView(
  onLoadMore: (page) {
    // Load more data for `page`
  },
  hasReachedMax: state.hasReachedMax,
  delegate: EnhancedDelegate(
    listOfData: yourDataList,
    status: EnhancedStatus.loaded,
  ),
  builder: (items, physics, reverse, shrinkWrap) {
    return ListView.builder(
      itemCount: items.length,
      physics: physics,
      shrinkWrap: shrinkWrap,
      reverse: reverse,
      itemBuilder: (context, index) {
        return ListTile(title: Text(items[index].toString()));
      },
    );
  },
)

Sliver-based view

EnhancedPaginatedView.slivers(
  onLoadMore: (page) {
    // Load more data for `page`
  },
  hasReachedMax: state.hasReachedMax,
  delegate: EnhancedDelegate<YourDataType>(
    listOfData: yourDataList,
    status: EnhancedStatus.loaded,
  ),
  builder: (context, data) {
    return SliverGrid.builder(
      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
        crossAxisCount: 2,
        crossAxisSpacing: 16,
        mainAxisSpacing: 16,
        childAspectRatio: 1,
      ),
      itemCount: data.length,
      itemBuilder: (BuildContext context, int index) {
        return GridWidget(item: data[index], index: index);
      },
    );
  },
)

Pull-to-refresh

Add onRefresh to the example above to enable pull-to-refresh in either scroll direction; without it, the refresh indicator is disabled. Customize its appearance with refreshBuilder:

EnhancedPaginatedView(
  // ...as above
  onRefresh: () async {
    // Trigger data refresh
  },
  refreshBuilder: (context, onRefresh, child) {
    return RefreshIndicator(
      color: Colors.white,
      backgroundColor: Colors.green,
      onRefresh: onRefresh,
      child: child,
    );
  },
)

Presentation with `EnhancedConfig`

config: controls how the list looks and behaves — scroll physics, header, scroll direction, cross-axis alignment, deduplication, and the loading/error/empty widget configs. It defaults to const EnhancedConfig(), so pass it only to override something:

EnhancedPaginatedView(
  // ...as above
  config: EnhancedConfig(
    header: const HeaderWidget(),
    removeDuplicatedItems: true,
    scrollDirection: Axis.vertical,
    errorPageConfig: ErrorPageConfig(
      onRetry: () => bloc.add(const FetchDataEvent(page: 1)),
    ),
    errorLoadMoreConfig: ErrorLoadMoreConfig(
      onRetry: (page) => bloc.add(FetchDataEvent(page: page)),
    ),
  ),
)

`EnhancedPaginationController`

An optional ChangeNotifier that tracks the current page and whether a load-more request isLoadingMore. If you don't pass one, EnhancedPaginatedView creates and disposes one internally. The page only advances when the delegate's status transitions from loading to loaded, so make sure your state management emits loading before each page load — including the first one.

final controller = EnhancedPaginationController();

EnhancedPaginatedView(
  // ...as above
  controller: controller,
)

If your app preloads the first page (starts with non-empty data and status loaded, without an initial loading status), create the controller with initialPage: 2 so the next requested page is correct:

final controller = EnhancedPaginationController(initialPage: 2);

You can also tune how early a load-more request fires via loadMoreThreshold (pixels from the end of the scrollable, default 200):

EnhancedPaginatedView(
  loadMoreThreshold: 400,
  // ...
)

API Reference