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 ValueNotifier over a PageableView that owns fetching, deduplication, retry, polling and caching for a single paginated stream. Generic over <PageKey, Item> so page keys can be int offsets, String cursors, 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:

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 toString output 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, and toString.
ToString
A mixin that provides customizable toString implementation using the same properties defined in EqualsAndHashCode.equalizedProperties.

Typedefs

Bool = bool
An alternative alias for a boolean value.
BoolCollection = List<Bool>
A collection of boolean values using the Bool alias.
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 Bool alias.
Checker<T> = Boolean Function(T value)
A function that takes a value of type T and 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 T and 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 Int alias.
Integer = int
An alternative alias for an integer value.
IntegerCollection = List<Int>
A collection of integers using the Integer alias.
IntegerSet = Set<Integer>
A set of unique integers using the Integer alias.
IntSet = Set<Integer>
A set of unique integers using the Int alias.
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 T and returns a value of type U.
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<Item>> Function(PageKey pageKey)
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.