pagination library

Smart Pagination Library

A comprehensive Flutter pagination library that provides flexible and powerful pagination solutions for REST APIs with support for multiple view types.

Features

  • Multiple Layout Support: ListView, GridView, PageView, StaggeredGridView, Column, Row
  • BLoC Pattern: Clean state management using flutter_bloc
  • Cursor & Offset Pagination: Support for both pagination strategies
  • Stream Support: Real-time updates via stream providers
  • Memory Management: Configurable page caching
  • Filtering & Refresh: Built-in filter and refresh listeners
  • Scroll Control: Programmatic scrolling to items or indices

Basic Usage

// 1. Define your data provider
Future<List<MyModel>> fetchData(PaginationRequest request) async {
  final response = await http.get('api/items?page=${request.page}');
  return (json.decode(response.body) as List)
      .map((e) => MyModel.fromJson(e))
      .toList();
}

// 2. Create a SmartPagination widget
SmartPagination<MyModel>(
  request: PaginationRequest(page: 1, pageSize: 20),
  dataProvider: fetchData,
  itemBuilder: (context, items, index) {
    return ListTile(title: Text(items[index].name));
  },
)

For advanced usage and examples, see the documentation.

Classes

AlignedGridView
A scrollable, 2D array of widgets placed according to the aligned layout.
BottomLoader
ChatObserverBouncingScrollPhysics
ChatObserverClampingScrollPhysics
ChatObserverClampinScrollPhysics
ChatScrollObserver
ChatScrollObserverCustomAdjustPositionDeltaModel
ChatScrollObserverCustomAdjustPositionModel
ChatScrollObserverHandlePositionResultModel
CommonOnceObserveNotificationResult<M extends ObserveModel, R extends ObserverHandleContextsResultModel<M>>
CustomErrorBuilder
A customizable error widget builder for pagination errors.
EmptyDisplay
EmptySeparator
ErrorDisplay
FuturePaginationProvider<T>
Future-based pagination provider for standard REST APIs.
GridObserverController
GridViewObserveDisplayingChildModel
GridViewObserveModel
GridViewObserver
GridViewObserverState
GridViewOnceObserveNotification
The Notification for Triggering an GridView observation
GridViewOnceObserveNotificationResult
InitialLoader
IPaginationChangeListener
Base interface for pagination change listeners that provides common functionality for both SmartPagination and DualPagination listeners.
IPaginationController<T>
Base interface for pagination controllers that provides common functionality for both SmartPagination and DualPagination controllers.
IPaginationCubit<T, StateType extends IPaginationState<T>>
Base interface for pagination cubits that provides common functionality for both SmartPagination and DualPagination cubits.
IPaginationErrorState<T>
Base interface for error pagination states.
IPaginationFilterChangeListener<T>
Base interface for pagination filter listeners.
IPaginationInitialState<T>
Base interface for pagination states that provides common functionality for both SmartPagination and DualPagination states.
IPaginationListCubit<T, StateType extends IPaginationState<T>>
Base interface for pagination cubits with list building capabilities.
IPaginationLoadedState<T>
Base interface for loaded pagination states.
IPaginationOrderChangeListener<T>
Base interface for pagination order listeners.
IPaginationRefreshedChangeListener
Base interface for pagination refresh listeners.
IPaginationScrollController<T>
Base interface for pagination controllers with scroll capabilities.
IPaginationState<T>
Base interface for pagination states that provides common functionality for both SmartPagination and DualPagination states.
ListObserverController
ListViewObserveDisplayingChildModel
ListViewObserveModel
ListViewObserver
ListViewObserverState
ListViewOnceObserveNotification
The Notification for Triggering an ListView observation
ListViewOnceObserveNotificationResult
MasonryGridView
A scrollable, 2D array of widgets placed according to the masonry layout.
MergedStreamPaginationProvider<T>
Merged streams pagination provider that combines multiple streams into one.
MixViewObserverState
NestedScrollUtil
ObserveDisplayingChildModel
ObserveModel
ObserverCore
ObserverIndexPositionModel
ObserverScrollDecisionNotification
A notification that the data of the specified index item is determined during the execution of the scrolling task.
ObserverScrollEndNotification
A notification that a scrolling task has stopped due to calling the jumpTo or animateTo method of ObserverController.
ObserverScrollInterruptionNotification
A notification that a scrolling task has interrupted due to calling the jumpTo or animateTo method of ObserverController.
ObserverScrollNotification
A notification of scrolling task.
ObserverScrollStartNotification
A notification that a scrolling task has started due to calling the jumpTo or animateTo method of ObserverController.
ObserverUtils
OverlayPositionData
Calculated position and size for the overlay.
OverlayPositioner
Utility class for calculating overlay position.
PaginateApiView<T>
PaginationMeta
Metadata describing the state of a paginated response.
PaginationProvider<T>
Unified pagination data provider that can be either Future-based or Stream-based.
PaginationRequest
Lightweight request descriptor used by the pagination cubit.
QuiltedGridRepeatPattern
Defines how a pattern is repeating.
QuiltedGridTile
A tile for SliverQuiltedGridDelegate.
RenderSliverMasonryGrid
A sliver that places multiple box children in a two dimensional arrangement.
RetryConfig
Configuration for retry behavior.
RetryHandler
Utility class for executing functions with retry and timeout logic.
ScrollViewOnceObserveNotification
ScrollViewOnceObserveNotificationResult
SliverAlignedGrid
A sliver that places multiple box children in a two dimensional arrangement.
SliverMasonryGrid
A sliver that places multiple box children in a two dimensional arrangement.
SliverMasonryGridParentData
Parent data structure used by RenderSliverMasonryGrid.
SliverObserveContext
SliverObserveContextToBoxAdapter
SliverObserverController
SliverQuiltedGridDelegate
Controls the layout of a quilted grid.
SliverSimpleGridDelegate
Controls the layout of tiles in a some slivers.
SliverSimpleGridDelegateWithFixedCrossAxisCount
Creates grid layouts with a fixed number of tiles in the cross axis.
SliverSimpleGridDelegateWithMaxCrossAxisExtent
Creates grid layouts with tiles that each have a maximum cross-axis extent.
SliverStairedGridDelegate
Controls the layout of tiles in a staired grid.
SliverViewObserver
SliverViewportObserveDisplayingChildModel
SliverViewportObserveModel
SliverWovenGridDelegate
Controls the layout of tiles in a woven grid.
SmartPagination<T>
SmartPaginationChangeListener
SmartPaginationColumn<T>
A paginated Column widget (non-scrollable) with automatic pagination support.
SmartPaginationController<T>
SmartPaginationCubit<T>
SmartPaginationError<T>
SmartPaginationFilterChangeListener<T>
SmartPaginationGridView<T>
A paginated GridView widget with automatic pagination support.
SmartPaginationInitial<T>
SmartPaginationListView<T>
A paginated ListView widget with automatic pagination support.
SmartPaginationLoaded<T>
SmartPaginationOrderChangeListener<T>
SmartPaginationPageView<T>
A paginated PageView widget with automatic pagination support.
SmartPaginationRefreshedChangeListener
SmartPaginationReorderableListView<T>
A paginated ReorderableListView widget with automatic pagination support.
SmartPaginationRow<T>
A paginated Row widget (horizontal non-scrollable) with automatic pagination support.
SmartPaginationStaggeredGridView<T>
A paginated StaggeredGridView widget with automatic pagination support.
SmartPaginationState<T>
SmartSearchBox<T>
A search box widget that connects to a SmartPaginationCubit for searching.
SmartSearchConfig
Configuration for search behavior.
SmartSearchController<T>
Controller for managing search state and connecting to SmartPaginationCubit.
SmartSearchDropdown<T>
A convenient widget that combines search functionality with a dropdown overlay showing paginated results from a SmartPaginationCubit.
SmartSearchOverlay<T>
A widget that combines SmartSearchBox with an overlay dropdown for results.
SmartSearchOverlayConfig
Configuration for the search overlay appearance and behavior.
SortOrder<T>
Configuration for sorting paginated items.
SortOrderCollection<T>
A collection of sort orders with a selected active order.
StaggeredGrid
A grid which lays out children in a staggered arrangement. Each child can have a different size. Wrap your children with a StaggeredGridTile to specify their size if it's different from a 1x1 tile.
StaggeredGridTile
Represents the size of a StaggeredGrid's tile.
StairedGridTile
A tile of a staired pattern.
StreamPaginationProvider<T>
Stream-based pagination provider for real-time updates.
WovenGridTile
A tile of a woven pattern.

Enums

ChatScrollObserverHandleMode
ChatScrollObserverHandlePositionType
ChatScrollObserverRefIndexType
NestedScrollUtilPosition
ObserverAutoTriggerObserveType
Define type that auto trigger observe.
ObserverRenderSliverType
Define type of the observed render sliver.
ObserverTriggerOnObserveType
Define type that trigger onObserve callback.
OverlayPosition
Position preference for the search overlay.
PaginateBuilderType
SortDirection
Defines the direction of sorting.

Mixins

ChatObserverScrollPhysicsMixin
ObserveDisplayingChildModelMixin
PaginationScrollToItemMixin
Base mixin for pagination controllers with scroll capabilities.
SmartPaginationScrollToItemMixin
A mixin for SmartPaginationController implementations that adds programmatic scrolling capabilities.

Typedefs

ChatScrollObserverCustomAdjustPosition = double? Function(ChatScrollObserverCustomAdjustPositionModel)
Customize the scroll position should be given new viewport dimensions.
ChatScrollObserverCustomAdjustPositionDelta = double? Function(ChatScrollObserverCustomAdjustPositionDeltaModel)
Customize the delta of the adjustPosition.
CompareBy<T> = int Function(T a, T b)
InsertAllCallback<T> = void Function(List<T> currentItems, Iterable<T> newItems)
Signature for a callback function that is called when items are inserted.
ItemComparator<T> = int Function(T a, T b)
A comparator function that compares two items of type T.
ListBuilder<T> = List<T> Function(List<T> list)
Signature for a function that builds a list from fetched items.
ObserverOnPrepareScrollToIndex = Future<bool> Function(ObservePrepareScrollToIndexModel)
Called when the ObserverController prepare to scroll to index with ObservePrepareScrollToIndexModel.
OnInsertionCallback<T> = void Function(List<T> items)
OnObserveAllCallback<M extends ObserveModel> = void Function(Map<BuildContext, M> resultMap)
The callback type of getting observed result map.
OnObserveCallback<M extends ObserveModel> = void Function(M result)
The callback type of getting observed result for first sliver.
OnObserveViewportCallback = void Function(SliverViewportObserveModel result)
The callback type of getting all slivers those are displayed in viewport.
PaginationDataProvider<T> = Future<List<T>> Function(PaginationRequest request)
Legacy typedef for backward compatibility (will be deprecated).
PaginationScrollToIndex = Future<bool> Function(int index, {double alignment, Curve curve, Duration duration, double offset})
Signature for a function that scrolls the pagination list to a specific index.
PaginationScrollToItem = Future<bool> Function(String itemId, {double alignment, Curve curve, Duration duration, double offset})
Signature for a function that scrolls the pagination list to a specific item ID.
PaginationStreamProvider<T> = Stream<List<T>> Function(PaginationRequest request)
Legacy typedef for backward compatibility (will be deprecated).
SmartPaginationScrollToIndex = Future<bool> Function(int index, {double alignment, Curve curve, Duration duration, double offset})
Signature for a function that scrolls the pagination list to a specific index.
SmartPaginationScrollToItem = Future<bool> Function(String itemId, {double alignment, Curve curve, Duration duration, double offset})
Signature for a function that scrolls the pagination list to a specific item ID.
WhereChecker<T> = bool Function(T item)

Exceptions / Errors

PaginationException
Custom exception types for pagination errors.
PaginationNetworkException
Exception thrown when a network request fails.
PaginationParseException
Exception thrown when data parsing fails.
PaginationRetryExhaustedException
Exception thrown when all retry attempts have been exhausted.
PaginationTimeoutException
Exception thrown when a network request times out.