super_scroll 1.0.0

A simple, lightweight, and powerful pagination library for Flutter.

Super Scroll

A simple, lightweight, and powerful pagination library for Flutter. Production ready and cross-platform stable.

SuperScroll makes it easy to add infinite scrolling to your lists or grids. It provides high-level "Super" widgets that handle pagination state, loading indicators, viewport filling, and error handling automatically with minimal boilerplate.

🚀 Features

• One-Stop Widgets: Use SuperListView or SuperGridView to implement pagination in seconds.
• Sliver Support: Integrated SuperSliverList and SuperSliverGrid for complex scrolling effects.
• In-built Masonry: Dependency-free SuperMasonryGridView for staggered/masonry layouts.
• Automatic Viewport Filling: Automatically triggers loadMore until the screen is filled or data ends.
• Granular Indicators: Specific widgets for first-page loading, new-page loading, errors, and empty states.
• Smart Refreshing: Supports both full-list Refresh (Pull-to-Refresh) and specific page refreshing.
• Selection Support: In-built multi-selection management with SuperScrollController.
• Lightweight & Efficient: Zero external layout dependencies, optimized for performance.

📦 Installation

Add super_scroll to your pubspec.yaml:

dependencies:
  super_scroll: ^latest_version

🛠 Usage

1. Initialize the Controller

The SuperScrollController manages the pagination state. You provide an onFetch callback that handles the actual data fetching logic.

final _controller = SuperScrollController<UserModel>(
  onFetch: (page) async {
    final response = await _userService.fetchUsers(page);
    return SuperScrollResult(
      items: response.users,
      hasMore: response.hasNextPage,
    );
  },
);

2. Use SuperListView

SuperListView provides a familiar API for paginated lists.

// Separated list with dividers
SuperListView.separated(
  controller: _controller,
  itemBuilder: (context, user, index) => ListTile(title: Text(user.name)),
  separatorBuilder: (context, index) => const Divider(),
  onRefresh: () => _controller.refresh(),
)

3. Use SuperGridView

For paginated grids, use SuperGridView.count or SuperGridView.extent.

SuperGridView.count(
  controller: _controller,
  crossAxisCount: 2,
  mainAxisSpacing: 8,
  crossAxisSpacing: 8,
  itemBuilder: (context, item, index) => GridItem(item),
)

4. Use SuperMasonryGridView

A dependency-free masonry grid that distributes items across columns.

SuperMasonryGridView(
  controller: _controller,
  crossAxisCount: 2,
  mainAxisSpacing: 12,
  crossAxisSpacing: 12,
  itemBuilder: (context, item, index) => MasonryItem(item),
)

5. Use SuperSliverList / SuperSliverGrid

Perfect for use within a CustomScrollView.

CustomScrollView(
  slivers: [
    SuperSliverList(
      controller: _controller,
      itemBuilder: (context, item, index) => MySliverTile(item),
    ),
  ],
)

🎨 Advanced Customization

Granular Pagination Indicators

You can customize exactly what is shown during different states of the pagination lifecycle.

SuperListView.builder(
  controller: _controller,
  firstPageProgressIndicator: CustomFirstLoadSpinner(),
  newPageProgressIndicator: CustomBottomLoader(),
  firstPageErrorIndicator: MyCustomErrorWidget(onRetry: () => _controller.loadMore()),
  newPageErrorIndicator: MyCustomBottomErrorWidget(),
  noItemsFoundIndicator: Center(child: Text('No results found')),
  noMoreItemsIndicator: Center(child: Text('End of list')),
  itemBuilder: (context, item, index) => MyTile(item),
)

Manual Refresh Management

• Full Refresh: _controller.refresh() clears all items and reloads from page 1.
• Page Refresh: _controller.refresh(page: 5) reloads only the 5th page and replaces the corresponding items in the list.

Raw SuperScroll

If you need a completely custom layout (e.g., inside a CustomScrollView), use the base SuperScroll widget.

SuperScroll(
  controller: _controller,
  child: ListView.builder(
    itemCount: _controller.items.length,
    itemBuilder: (context, index) => MyItem(_controller.items[index]),
  ),
)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue for any bugs or feature requests.

📄 License

MIT License