ApiPaginator<T, E> class

Page-number or cursor-based pagination with built-in state management.

Eliminates the 50-80 lines of boilerplate needed per list screen (page counter, hasMore flag, loading state, append logic).

Page-number pagination

final paginator = ApiPaginator<Gallery, ApiError>(
  request: (page) => dio.get('/galleries', queryParameters: {'page': page}),
  parser:  (json) => Gallery.fromJson(json),
  pageSize: 20,
);

await paginator.loadFirst();
await paginator.loadNext(); // call on scroll end

paginator.items        // List<Gallery>
paginator.hasMore      // bool
paginator.isLoading    // bool
paginator.currentPage  // int
paginator.state        // ApiState<List<Gallery>, ApiError>

Cursor-based pagination (e.g. Strapi v5)

final paginator = ApiPaginator<Photo, ApiError>.cursor(
  request: (cursor) => dio.get('/photos',
    queryParameters: cursor != null ? {'cursor': cursor} : {}),
  parser:  (json) => Photo.fromJson(json),
  cursorExtractor: (response) => response['meta']['nextCursor'] as String?,
);

Flutter widget integration

// Rebuild on state changes by listening to the stream
paginator.stream.listen((_) => setState(() {}));

// Or use PaginatedListView
PaginatedListView(
  paginator: _paginator,
  itemBuilder: (ctx, item) => GalleryCard(item),
  loadingBuilder: () => const GalleryShimmer(),
  emptyBuilder:   () => const EmptyGalleries(),
)

Constructors

ApiPaginator({required Future<Response> request(int page), required T parser(dynamic json), List<T> listParser(dynamic json)?, E errorParser(Map<String, dynamic>)?, int pageSize = 20, bool resetOnRefresh = true})

Page-number pagination.

ApiPaginator.cursor({required Future<Response> request(String? cursor), required T parser(dynamic json), required String? cursorExtractor(dynamic responseData), List<T> listParser(dynamic json)?, E errorParser(Map<String, dynamic>)?, int pageSize = 20, bool resetOnRefresh = true})

Cursor-based pagination.

Properties

currentPage → int

no setter

hashCode → int

The hash code for this object.

no setter, inherited

hasMore → bool

no setter

isEmpty → bool

no setter

isLoading → bool

no setter

items → List<T>

no setter

pageSize → int

final

resetOnRefresh → bool

Whether to reset items on loadFirst (default: true)

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

state → ApiState<List<T>, E>

no setter

Methods

addListener(void listener()) → void

Register a callback that fires on every state change.

loadFirst() → Future<void>

Load the first page (or refresh).

loadNext() → Future<void>

Load the next page. No-op if already loading or no more pages.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

removeListener(void listener()) → void

Remove a previously registered listener.

reset() → void

Reset paginator to initial state without triggering a network request.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited