Flutter Pagination Pro #

A lightweight, zero-dependency Flutter pagination package.
Supports infinite scroll, load more button, and numbered pagination.

Features #

• 🚀 Zero dependencies - Pure Flutter, no external packages
• 📜 Infinite Scroll - Auto-loads when scrolling near the bottom
• 🔘 Load More Button - Manual trigger for loading next page
• 🔢 Numbered Pagination - Traditional page navigation
• 🎨 Fully Customizable - Override any widget (loading, error, empty states)
• 🔄 Controller Support - Programmatic refresh, retry, and state access
• ✅ Type-safe - Generic type support for your data models
• 📱 Cross-platform - Works on iOS, Android, Web, macOS, Windows, Linux

Installation #

Add to your pubspec.yaml:

dependencies:
  flutter_pagination_pro: ^latest

Then run:

flutter pub get

Quick Start #

Infinite Scroll (Default) #

The simplest way to add pagination - items load automatically as user scrolls:

PaginationListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => ListTile(
    leading: CircleAvatar(child: Text(user.name[0])),
    title: Text(user.name),
    subtitle: Text(user.email),
  ),
)

Load More Button #

Let users control when to load more items:

PaginationListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserCard(user: user),
  paginationType: PaginationType.loadMore,
)

Grid View #

Perfect for image galleries, product listings, etc:

PaginationGridView<Photo>(
  fetchPage: (page) => api.getPhotos(page: page),
  itemBuilder: (context, photo, index) => PhotoCard(photo: photo),
  gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 2,
    mainAxisSpacing: 8,
    crossAxisSpacing: 8,
  ),
)

Numbered Pagination #

Traditional page navigation with page numbers:

NumberedPagination(
  totalPages: 20,
  currentPage: _currentPage,
  onPageChanged: (page) => setState(() => _currentPage = page),
)

Using Controller #

For programmatic control over pagination (refresh, retry, access state):

class _MyPageState extends State<MyPage> {
  late final PaginationController<User> _controller;

  @override
  void initState() {
    super.initState();
    _controller = PaginationController<User>(
      fetchPage: (page) => api.getUsers(page: page),
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Users'),
        actions: [
          IconButton(
            icon: Icon(Icons.refresh),
            onPressed: () => _controller.refresh(),
          ),
        ],
      ),
      body: PaginationListView<User>.withController(
        controller: _controller,
        itemBuilder: (context, user, index) => UserTile(user: user),
      ),
    );
  }
}

Controller Methods #

Controller Properties #

Customization #

Custom Loading Widget #

PaginationListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  firstPageLoadingBuilder: (context) => Center(
    child: Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        CircularProgressIndicator(),
        SizedBox(height: 16),
        Text('Loading users...'),
      ],
    ),
  ),
)

Custom Error Widget #

PaginationListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  firstPageErrorBuilder: (context, error, onRetry) => Center(
    child: Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Icon(Icons.error, size: 64, color: Colors.red),
        SizedBox(height: 16),
        Text('Failed to load: $error'),
        SizedBox(height: 16),
        ElevatedButton(
          onPressed: onRetry,
          child: Text('Try Again'),
        ),
      ],
    ),
  ),
)

Custom Empty State #

PaginationListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  emptyBuilder: (context) => Center(
    child: Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Icon(Icons.inbox, size: 64, color: Colors.grey),
        SizedBox(height: 16),
        Text('No users found'),
      ],
    ),
  ),
)

Custom Load More Button #

PaginationListView<User>(
  fetchPage: (page) => api.getUsers(page: page),
  itemBuilder: (context, user, index) => UserTile(user: user),
  paginationType: PaginationType.loadMore,
  loadMoreButtonBuilder: (context, onLoadMore, isLoading) => Padding(
    padding: EdgeInsets.all(16),
    child: ElevatedButton(
      onPressed: isLoading ? null : onLoadMore,
      child: isLoading
          ? SizedBox(
              width: 20,
              height: 20,
              child: CircularProgressIndicator(strokeWidth: 2),
            )
          : Text('Load More'),
    ),
  ),
)

Parameters #

PaginationListView / PaginationGridView #

PaginationConfig #

NumberedPagination #

NumberedPaginationConfig #

Example #

Check out the example directory for a complete demo app showcasing all features.

License #

This project is licensed under the MIT License - see the LICENSE file for details.