flutter_pageable library
flutter_pageable
Pagination for Flutter: typed page controllers, scrollable views,
multi-source interleaved feeds, caching, retry, polling and
pull-to-refresh — with zero third-party dependencies beyond Flutter
itself and meta.
Import
import 'package:flutter_pageable/flutter_pageable.dart';
Core concepts
- PageableController — a
ValueNotifierover a PageableView that owns fetching, deduplication, retry, polling and caching for a single paginated stream. Generic over<PageKey, Item>so page keys can beintoffsets,Stringcursors, or anything else. - PageableView — the immutable state: loaded PageResults, current PageableStatus, cursors and the last error.
- PageResult — one fetched page: a
[PageKey]plus its items. - PageableStatus — the unified loading/error/completed state machine shared by controllers, views and delegates.
Views
Drop-in scrollables that listen to a PageableController and render items, loading indicators and errors:
Each takes a PageableBuilderDelegate, which defines the item builder plus optional widgets for every pagination state (first-page loading, next-page loading, errors, empty list, end-of-list).
Interleaved multi-source feeds
InterleavablePageableController merges several independent PageableSources — each with its own pagination cursor — into one unified feed, driven by an InterleaveStrategy such as RoundRobinInterleaveStrategy, PriorityInterleaveStrategy or CustomInterleaveStrategy. Per-source errors are isolated, so one failing source never blanks the others.
Utilities
The package also bundles a small set of utilities it was built on, free to use:
- Optional — null-safe container with
map/flatMap/filter/orElse - Extension methods on primitives (IntExtensions, StringExtensions, ListExtensions, MapExtensions, …)
- Stream helpers (IntStream, DoubleStream, GenericStream) and Collector for reduce-style aggregation
- PageableLogger for opt-in debug logging (
showLog: true) - PageableSeparatorStrategy for index-aware separators
Classes
- AbstractPageRequest
- Base class for paged requests that define page number and page size.
-
BaseStream<
T, S extends BaseStream< T, S> > - Base interface for streams, which are sequences of elements supporting sequential and parallel aggregate operations.
- BigInteger
- A wrapper class for arbitrary precision integers.
-
Collector<
T, A, R> - A mutable reduction operation that accumulates input elements into a mutable result container, optionally transforming the accumulated result into a final representation after all input elements have been processed.
- CryptoUuidRangeBuilder
- Cryptographically secure random number generator using dart:math.Random.secure().
-
CustomInterleaveStrategy<
Item> - An InterleaveStrategy that delegates both item ordering and fetch routing to user-provided functions.
- DoubleStream
-
A sequence of primitive
double-valued elements supporting sequential and parallel aggregate operations. - FloatingConfig
- Configuration class for specifying the position and size of a floating widget.
-
GenericStream<
T> - A sequence of elements supporting sequential and parallel aggregate operations.
- Instance
-
A utility class for type checking, similar to Java's
instanceof. It also provides additional methods for type checking. -
InterleavablePageableController<
PageKey, Item> - A PageableController that orchestrates multiple independent paginated data sources and merges them into a single, unified feed.
-
InterleavedSourceState<
Item> - An immutable snapshot of a single data source's state within an InterleavablePageableController.
-
InterleaveStrategy<
Item> - Abstract strategy that determines two things for an InterleavablePageableController:
- IntStream
-
A sequence of primitive
int-valued elements supporting sequential and parallel aggregate operations. -
ItemMetadata<
T> - Configuration for an item within a list.
- KeysetPageScrollPosition
- Represents a key-set (cursor-based) scroll position in a collection.
- Limit
- A value object representing an upper bound (limit) typically used in pagination, query constraints, or result-size restrictions.
- Limiting
- Marker mixin indicating that a type provides limiting behavior.
- MathUuidRangeBuilder
- Fast, non-cryptographic random number generator using dart:math.Random.
-
MemoryPage<
T> -
A small, in-memory implementation of Page<T> backed by a concrete
List<T>. - OffsetPageScrollPosition
-
Represents an offset-based scroll position, commonly used for
index-based pagination (e.g., SQL
LIMIT/OFFSET, list slicing, sequential pagination). -
Optional<
T> - A container object which may or may not contain a non-null value.
-
Page<
T> - Represents a full page of data in a paginated dataset.
- Pageable
- Represents a pagination request describing which slice of data should be retrieved from a paged resource.
-
PageableBuilder<
PageKey, Item> - Widget that builds UI based on the current PageableView state using delegate and layout builder patterns.
-
PageableBuilderDelegate<
Item> - A delegate class used for building children and state indicators in a paginated list view.
-
PageableCache<
PageKey, Item> - Storage contract for persisting PageableCacheSnapshots across controller lifetimes.
-
PageableCacheSnapshot<
PageKey, Item> - An immutable snapshot of paginated state that can be persisted and later restored.
-
PageableController<
PageKey, Item> - Controller that manages pagination state and data fetching logic.
-
PageableGridView<
Page, Item> - A scrollable grid view that supports pagination.
-
PageableLayoutBuilder<
PageKey, Item> - A base builder widget for creating paginated scrollable layouts.
-
PageableListener<
PageKey, Item> - A widget that listens to a PageableController and rebuilds whenever the pagination state changes.
-
PageableListView<
Page, Item> - A scrollable list view that supports pagination.
- PageableLogger
- Optional logger interface used for logging pageable-related messages.
-
PageablePageView<
Page, Item> - A scrollable page view that supports pagination.
-
PageableSource<
PageKey, Item> - A self-contained paginated data source that contributes items to an InterleavablePageableController.
-
PageableStaggeredView<
Page, Item> - A paginated staggered (masonry-like) view built with core Flutter widgets only.
-
PageableView<
PageKey, Item> - Represents a pagination request describing which slice of data should be retrieved from a paged resource.
- PageRequest
- Represents a concrete, paged request with page number, page size, and optional PageSort.
-
PageResult<
PageKey, Item> - Represents the result of a single page fetch operation in a paginated data source.
- PageScrollPosition
- Represents a position in a scrollable or paginated collection.
-
PageSlice<
T> - Represents a slice of a paginated dataset, containing a subset of items along with metadata about pagination and sorting.
-
PageSlicedChunk<
T> -
Concrete implementation of
Slice<T>backed by a Pageable and a stream of elements. - PageSort
- Represents an ordered collection of sorting instructions, each expressed as a PageSortOrder.
- PageSortOrder
- Represents a single sorting instruction consisting of:
-
PriorityInterleaveStrategy<
Item> - An InterleaveStrategy that concatenates items from sources ordered by priority, with lower priority numbers appearing first.
- PullToRefresh
- A customizable pull-to-refresh widget that adapts to different platforms.
- RegexUtils
- A collection of commonly used regular expressions, provided as constants.
-
RoundRobinInterleaveStrategy<
Item> - An InterleaveStrategy that takes a fixed number of items from each source in sequential rounds.
- StandardDoubleStream
- Private implementation of DoubleStream that wraps an Iterable of doubles.
-
StandardGenericStream<
T> - Implementation of GenericStream that wraps an Iterable and provides some basic stream operations.
- StandardIntStream
- Private implementation of IntStream.
- StreamSupport
- Low-level utility methods for creating and manipulating streams.
- ToStringOptions
-
Configuration options for customizing
toStringoutput in JetLeaf objects. - Unpaged
- Represents an unpaged pagination request, i.e., a sentinel object indicating that no pagination boundaries should be applied.
- Uuid
- A powerful, secure implementation of Universally Unique Identifiers (UUIDs) following RFC 4122 specifications.
- UuidRangeBuilder
- Abstract base class for generating random numbers used in UUID creation.
Enums
- PageableStatus
- Enum representing the various states of a pageable data source.
- PageScrollDirection
- Represents the direction of a scrolling action, such as navigating through paginated results, lists, or timeline-like structures.
- PageSortDirection
- Represents the direction in which results should be sorted.
- PullToRefreshType
- Enum representing the refresh indicator type.
Mixins
- EqualsAndHashCode
-
Mixin-style contract for value-based equality,
hashCode, andtoString. - ToString
- A mixin that provides customizable toString implementation using the same properties defined in EqualsAndHashCode.equalizedProperties.
Extensions
- BoolExtensions on bool
- DateTimeExtensions on DateTime
- DoubleExtensions on double
- DurationExtension on Duration
- DynamicExtensions on dynamic
- IntExtensions on int
-
IterableExtension
on Iterable<
T> -
ListExtensions
on List<
T> -
MapExtensions
on Map<
K, V> - NumExtensions on num
-
PageableIterableExtension
on Iterable<
T> -
PageableListExtension
on List<
T> - PageableStatusExtension on PageableStatus
- Extension providing convenient boolean getters for PageableStatus.
-
PageResultBuilderExtension
on List<
Item> - PullToRefreshTypeExtension on PullToRefreshType
-
This extension simplifies status checks by replacing
==comparisons with readable getters. - StringExtensions on String
- TExtensions on T?
Typedefs
- Bool = bool
- An alternative alias for a boolean value.
-
BoolCollection
= List<
Bool> -
A collection of boolean values using the
Boolalias. - Boolean = bool
- A shorthand for a boolean value.
-
BooleanCollection
= List<
Bool> - A collection of boolean values.
-
BooleanSet
= Set<
Boolean> - A set of unique boolean values.
-
BoolSet
= Set<
Boolean> -
A set of unique boolean values using the
Boolalias. -
Checker<
T> = Boolean Function(T value) -
A function that takes a value of type
Tand returns a boolean. -
ConditionTester<
T> = bool Function(T value) -
A typedef for a function that tests a condition on a value of type
T. -
Consumer<
T> = void Function(T value) -
A function that takes a value of type
Tand performs an operation on it. -
DateTimeCollection
= List<
DateTime> - A collection of date time values.
-
DateTimeSet
= Set<
DateTime> - A set of unique date time values.
- Double = double
- A shorthand for a double value.
-
DoubleCollection
= List<
Double> - A collection of double values.
-
DoubleSet
= Set<
Double> - A set of unique double values.
-
DurationCollection
= List<
Duration> - A collection of duration values.
-
DurationSet
= Set<
Duration> - Represents a set of unique duration values.
- ExceptionSupplier = Object Function()
- A function that returns an exception object.
- Int = int
- A shorthand for an integer value.
-
IntCollection
= List<
Int> -
A collection of integers using the
Intalias. - Integer = int
- An alternative alias for an integer value.
-
IntegerCollection
= List<
Int> -
A collection of integers using the
Integeralias. -
IntegerSet
= Set<
Integer> -
A set of unique integers using the
Integeralias. -
IntSet
= Set<
Integer> -
A set of unique integers using the
Intalias. -
ItemWidgetBuilder<
ItemType> = Widget Function(BuildContext context, ItemMetadata< ItemType> metadata) - A typedef for constructing a widget for a specific item in a list.
-
JsonMap
= Map<
String, dynamic> - A type alias for structured key-value storage used in repositories.
-
JsonMapCollection
= List<
JsonMap> - A type alias for a collection of structured repository data.
-
JsonString
= Map<
String, String> - A JSON-like structure where both keys and values are strings.
-
JsonUtilsDecoder<
T> = T Function(JsonMap json) -
A typedef for a function that decodes a JSON map into an object of type
T. -
Mapper<
T, U> = U Function(T value) -
A function that takes a value of type
Tand returns a value of typeU. -
NextPageKeyGenerator<
PageKey, Item> = PageKey? Function(PageKey currentPageKey, List< Item> currentPageItems, int totalLoadedItems) - Function that generates the next page key based on the current page info.
-
PageableCallback<
PageKey, Item> = FutureOr< List< Function(PageKey pageKey)Item> > - Fetches a page of items synchronously or asynchronously.
-
PageableLayoutWidgetBuilder<
PageKey, Item> = Widget Function(BuildContext context, PageableView< PageKey, Item> pageable, VoidCallback fetchFirstPage, VoidCallback fetchNextPage, VoidCallback retry) - Signature for builder functions that build a widget based on the current pageable state and control callbacks.
- PageableRetryCallback = void Function(int attempt, Object error, StackTrace stackTrace, Duration delay)
- Notifies callers when a pagination retry is scheduled.
- PageableRetryDelayBuilder = Duration Function(int attempt)
- Calculates the delay before the next pagination retry.
- PageableRetryIf = bool Function(Object error, StackTrace stackTrace, int attempt)
- Determines whether a failed pagination request should be retried.
- PageableSeparatorStrategy = Boolean Function(int index)
- A strategy function for determining whether to insert a separator between items in a paginated list.
-
PageableStatusWidgetBuilder<
Item> = Widget Function(BuildContext context, int itemCount, WidgetBuilder? indicatorBuilder, IndexedWidgetBuilder itemBuilder) - Signature for layout builders that receive the total item count, an optional indicator builder, and the item builder.
- PageableWidgetBuilder = Widget Function(BuildContext context, int index, WidgetBuilder? widgetBuilder, IndexedWidgetBuilder itemBuilder)
- Signature for building a widget that handles various paging states such as loading, error, or completed.
-
PreviousPageKeyGenerator<
PageKey, Item> = PageKey? Function(PageKey currentFirstPageKey, List< Item> currentFirstPageItems, int totalLoadedItems) - Function that generates the previous page key based on the current first page.
-
StringCollection
= List<
String> - A collection of strings.
-
StringSet
= Set<
String> - A set of unique strings.
-
Supplier<
T> = T Function() -
A function that returns a value of type
T.
Exceptions / Errors
- FlutterPageableException
- A custom exception class to handle various error scenarios in the app, providing information such as error messages, status codes, and specific error flags for rerouting or handling specific conditions.