Infinite Scroll List View

A powerful, flexible, and efficient infinite scrolling list view for Flutter — with built-in sorting, deduplication, dynamic mutations, sliver support, and a minimal API that stays out of your way.

Why this package?

Most infinite-scroll packages just load pages. This one manages your entire list lifecycle:

Pages load automatically as the user scrolls — zero boilerplate.
Items inserted mid-session land in the right sorted position instantly.
Duplicates are detected and merged, not doubled.
State (isLoading, isEndOfResults) is readable at any time without subscribing to streams.
Works as a regular widget or as a sliver inside a CustomScrollView.

Features


Automatic pagination	New pages load as the sentinel scrolls into view
Smart end-of-page detection	`pageSize`, `isEndOfPage`, or the default empty-page heuristic
Custom comparator	Full control over sort order — items insert at the right position every time
Deduplication + `pick`	Zero == same item; choose which version to keep
Dynamic mutations	`add()`, `update()`, `removeItem()`, `removeWhere()` — all animated
State control	`clear()`, `replace()`, `reload()`, `isLoading`, `isEndOfResults` via `GlobalKey`
Sliver variant	`SliverInfiniteScrollListView` composes with app bars, headers, grids
One-shot loader	`.once` constructor — no index checks, no empty-page round-trip
Simple builder	`simpleBuilder` drops unused `index` and `animation` params
Separators	`separatorBuilder` — like `ListView.separated`, but paginated
Remove animations	`removeAnimationBuilder` receives the removed item for exit transitions
Pull-to-refresh	Built-in `RefreshIndicator`, opt out with `refreshable: false`
Error handling	`errorBuilder` for full-page errors, `elementErrorBuilder` for inline retry
Horizontal lists	`.horizontal` named constructor
Batch insert fast-path	No `betweenItemRenderDelay`? All items insert in a single frame

Installation

dependencies:
  infinite_scroll_list_view: ^1.3.0

flutter pub get

Quick start

Paginated list

InfiniteScrollListView<Post>(
  pageSize: 20,
  pageLoader: (page) => api.fetchPosts(page: page, size: 20),
  elementBuilder: simpleBuilder((context, post) => PostTile(post)),
)

Single-page list (load once, done)

No more if (index == 0) fetch else return []:

InfiniteScrollListView.once(
  oncePageLoader: () => api.fetchFeatured(),
  elementBuilder: simpleBuilder((context, post) => PostTile(post)),
)

Inside a CustomScrollView

CustomScrollView(
  slivers: [
    SliverAppBar(title: Text('Feed')),
    SliverInfiniteScrollListView<Post>(
      pageSize: 20,
      pageLoader: (page) => api.fetchPosts(page: page, size: 20),
      elementBuilder: simpleBuilder((context, post) => PostTile(post)),
    ),
  ],
)

Sorting and deduplication

Provide a comparator and items always land in the right position — whether they come from pagination or a live push.

// Positive → a before b. Zero → same item (triggers update). Negative → a after b.
int compareByDate(Post a, Post b) => b.createdAt.compareTo(a.createdAt); // newest first

When two items compare as equal, the pick function decides which version to keep:

pick: (current, incoming) => incoming.updatedAt > current.updatedAt ? incoming : current,

Live mutations

Use a GlobalKey to mutate the list from anywhere — items animate in and out automatically.

final key = GlobalKey<InfiniteScrollListViewState<Message>>();

// Elsewhere — e.g. a WebSocket handler:
key.currentState!.add(newMessage);       // inserts at the sorted position
key.currentState!.update(editedMessage); // updates in-place
key.currentState!.removeItem(message);  // animated removal
key.currentState!.reload();             // clears and re-fetches from page 0

State control

if (key.currentState!.isLoading) showSpinner();
if (key.currentState!.isEndOfResults) showEndBanner();

await key.currentState!.clear();          // empty list, reset pagination, no fetch
await key.currentState!.replace(items);   // swap contents without animation

Full example — live chat feed

class ChatScreen extends StatefulWidget { ... }

class _ChatScreenState extends State<ChatScreen> {
  final _key = GlobalKey<InfiniteScrollListViewState<Message>>();

  @override
  void initState() {
    super.initState();
    socket.onMessage((msg) => _key.currentState?.add(msg));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Chat')),
      body: InfiniteScrollListView<Message>(
        key: _key,
        pageSize: 30,
        pageLoader: (page) => api.fetchMessages(page: page, size: 30),
        comparator: (a, b) => b.sentAt.compareTo(a.sentAt), // newest first
        pick: (current, incoming) => incoming,
        elementBuilder: simpleBuilder((context, msg) => MessageBubble(msg)),
        errorBuilder: (context, error) => RetryWidget(onRetry: () => _key.currentState!.reload()),
        separatorBuilder: (context, index) => const Divider(height: 1),
      ),
    );
  }
}

API reference