Smart Pagination #

A powerful, flexible, and easy-to-use Flutter pagination library with built-in BLoC state management, advanced error handling, and beautiful UI components. Perfect for REST APIs, real-time streams, and complex data requirements.

Transport agnostic: Bring your own async function and enjoy consistent, production-ready pagination UI.

✨ Why Smart Pagination? #

• 🚀 Zero boilerplate - Get paginated lists running in minutes with minimal code
• 🎨 6+ view types - ListView, GridView, PageView, StaggeredGrid, and more
• 🛡️ Production-ready error handling - 6 beautiful error widget styles included
• ⚡ Smart preloading - Automatically loads data before users reach the end
• 🔄 Real-time support - Works seamlessly with Streams and Futures
• 📱 State separation - Different UI for first page vs load more states
• 🎛️ Data operations - Programmatic add, remove, update, clear via cubit
• 🧩 Highly customizable - Every aspect can be customized to match your design
• 🎯 Type-safe - Full generic type support throughout the library
• 🧪 Well tested - 60+ unit tests ensuring reliability

📚 Table of Contents #

• Installation
• Quick Start
• Features
• Data Operations
• Data Age & Expiration
• Error Handling
• View Types
• Advanced Usage
• Example App
• API Reference
• Contributing

📦 Installation #

Add to your pubspec.yaml:

dependencies:
  smart_pagination: ^0.0.7

Install it:

flutter pub get

Import it:

import 'package:smart_pagination/pagination.dart';

🚀 Quick Start #

1. Basic ListView Pagination #

The simplest way to add pagination to your app:

import 'package:smart_pagination/pagination.dart';
import 'package:flutter/material.dart';

class ProductsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Products')),
      body: SmartPagination<Product>.withProvider(
        request: PaginationRequest(page: 1, pageSize: 20),
        provider: PaginationProvider.future(
          (request) => apiService.fetchProducts(request),
        ),
        itemBuilder: (context, items, index) {
          final product = items[index];
          return ListTile(
            leading: Image.network(product.imageUrl),
            title: Text(product.name),
            subtitle: Text('\$${product.price}'),
          );
        },
      ),
    );
  }
}

That's it! You now have a fully functional paginated list with:

• ✅ Automatic loading of next pages
• ✅ Loading indicators
• ✅ Error handling with retry
• ✅ Empty state handling
• ✅ Pull-to-refresh support

2. GridView Pagination #

Switch to a grid layout by changing one line:

SmartPagination<Product>.withProvider(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(
    (request) => apiService.fetchProducts(request),
  ),
  itemBuilderType: PaginateBuilderType.gridView,
  gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 2,
    childAspectRatio: 0.75,
    crossAxisSpacing: 10,
    mainAxisSpacing: 10,
  ),
  itemBuilder: (context, items, index) {
    final product = items[index];
    return ProductCard(product: product);
  },
)

3. With Custom Error Handling #

Add beautiful error states:

SmartPagination<Product>.withProvider(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  itemBuilder: (context, items, index) => ProductCard(items[index]),

  // Beautiful Material Design error for first page
  firstPageErrorBuilder: (context, error, retry) {
    return CustomErrorBuilder.material(
      context: context,
      error: error,
      onRetry: retry,
      title: 'Oops! Something went wrong',
      message: 'Unable to load products. Please try again.',
    );
  },

  // Compact inline error for load more
  loadMoreErrorBuilder: (context, error, retry) {
    return CustomErrorBuilder.compact(
      context: context,
      error: error,
      onRetry: retry,
    );
  },
)

✨ Features #

🎨 Layout Support #

🛡️ Advanced Error Handling #

6 Pre-Built Error Widget Styles

1. Material Design - Full-screen error with icon, title, and message
2. Compact - Inline error for load more scenarios
3. Card - Elevated card-style error display
4. Minimal - Simple text-based error
5. Snackbar - Bottom notification-style error
6. Custom - Bring your own error widget

Error State Separation

Different error UIs for different scenarios:

• First Page Error - Full-screen, detailed error when initial load fails
• Load More Error - Compact, inline error when pagination fails

SmartPagination<Product>.withProvider(
  // ... other properties

  // Full-screen error for initial load
  firstPageErrorBuilder: (context, error, retry) {
    return CustomErrorBuilder.material(
      context: context,
      error: error,
      onRetry: retry,
    );
  },

  // Compact error for pagination
  loadMoreErrorBuilder: (context, error, retry) {
    return CustomErrorBuilder.compact(
      context: context,
      error: error,
      onRetry: retry,
    );
  },
)

🔄 Pagination Strategies #

• Offset Pagination - Traditional page-based (?page=2&pageSize=20)
• Cursor Pagination - Efficient cursor-based (?cursor=abc123&limit=20)
• Lazy Loading - Automatic loading as user scrolls
• Smart Preloading - Load items 3 items before reaching the end (configurable)
• Memory Management - Keep only N pages in memory to optimize performance

📡 Data Sources #

Future Provider (REST APIs)

PaginationProvider.future(
  (request) => apiService.fetchProducts(request),
)

Stream Provider (Real-time)

PaginationProvider.stream(
  (request) => firestore.collection('products').snapshots(),
)

Merged Streams

PaginationProvider.mergeStreams(
  (request) => [
    regularProductsStream(request),
    featuredProductsStream(request),
  ],
)

🔁 Retry Mechanisms #

1. Manual Retry

User clicks a button to retry:

firstPageErrorBuilder: (context, error, retry) {
  return ElevatedButton(
    onPressed: retry,
    child: Text('Try Again'),
  );
}

2. Automatic Retry with Exponential Backoff

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  retryConfig: RetryConfig(
    maxAttempts: 3,
    initialDelay: Duration(seconds: 1),
    maxDelay: Duration(seconds: 10),
    shouldRetry: (error) => error is NetworkException,
  ),
  itemBuilder: (context, items, index) => ProductCard(items[index]),
)

3. Auto Retry with Countdown

Show a countdown timer before auto-retry

4. Limited Attempts

Maximum retry attempts with exhaustion handling

See example app for complete implementations.

🎯 Smart Preloading #

Load data before users reach the end:

SmartPagination.listViewWithProvider<Product>(
  // ... other properties

  // Load when user is 3 items away from the end (default: 3)
  invisibleItemsThreshold: 3,
)

Adjust based on your needs:

• invisibleItemsThreshold: 5 - More aggressive preloading
• invisibleItemsThreshold: 1 - Load just before reaching end
• invisibleItemsThreshold: 0 - Load only when reaching end

🔍 Filtering & Search #

Server-Side Filtering

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(
    page: 1,
    pageSize: 20,
    filters: {
      'category': 'electronics',
      'minPrice': 100,
      'maxPrice': 1000,
      'search': searchQuery,
    },
  ),
  provider: PaginationProvider.future(fetchProducts),
  itemBuilder: (context, items, index) => ProductCard(items[index]),
)

Client-Side Filtering

final filterListener = SmartPaginationFilterChangeListener<Product>();

SmartPagination.withCubit(
  cubit: cubit,
  filterListeners: [filterListener],
  itemBuilder: (context, items, index) => ProductCard(items[index]),
)

// Apply filter
filterListener.searchTerm = (product) =>
  product.name.toLowerCase().contains(searchQuery.toLowerCase());

⚡ Performance Features #

• Lazy Building - Items built only when visible
• Smart Preloading - Configurable preload threshold
• Memory Optimization - Page-based caching (maxPagesInMemory)
• Efficient Rendering - Optimized for large lists
• Cache Extent Control - Customize viewport caching

🎨 UI Customization #

Every aspect of the UI can be customized:

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  itemBuilder: (context, items, index) => ProductCard(items[index]),

  // Loading states
  firstPageLoadingBuilder: (context) => CustomLoader(),
  loadMoreLoadingBuilder: (context) => BottomLoader(),

  // Empty state
  firstPageEmptyBuilder: (context) => EmptyState(),

  // Error states
  firstPageErrorBuilder: (context, error, retry) => ErrorWidget(),
  loadMoreErrorBuilder: (context, error, retry) => InlineError(),

  // No more items
  loadMoreNoMoreItemsBuilder: (context) => EndOfList(),

  // Separators
  separator: Divider(),

  // Scroll behavior
  physics: BouncingScrollPhysics(),
  padding: EdgeInsets.all(16),
  shrinkWrap: true,
  reverse: false,
)

🎛️ Data Operations #

The SmartPaginationCubit provides powerful data manipulation methods that can be called from anywhere in your app. These operations automatically update the UI.

Accessing the Cubit #

// Create and store the cubit reference
late SmartPaginationCubit<Product> cubit;

@override
void initState() {
  super.initState();
  cubit = SmartPaginationCubit<Product>(
    request: PaginationRequest(page: 1, pageSize: 20),
    provider: PaginationProvider.future(fetchProducts),
  );
}

// Use in your widget
SmartPagination.listViewWithCubit<Product>(
  cubit: cubit,
  itemBuilder: (context, items, index) => ProductCard(items[index]),
)

Insert Operations #

Insert Single Item

// Insert at the beginning (default)
cubit.insertEmit(newProduct);

// Insert at specific index
cubit.insertEmit(newProduct, index: 5);

Insert Multiple Items

cubit.insertAllEmit([product1, product2, product3]);
cubit.insertAllEmit(newProducts, index: 10);

Remove Operations #

Remove by Item

final wasRemoved = cubit.removeItemEmit(productToRemove);
if (wasRemoved) {
  print('Product removed successfully');
}

Remove by Index

final removedItem = cubit.removeAtEmit(0);
if (removedItem != null) {
  print('Removed: ${removedItem.name}');
}

Remove by Condition

// Remove all products with price > 100
final count = cubit.removeWhereEmit((item) => item.price > 100);
print('Removed $count expensive products');

// Remove out-of-stock items
cubit.removeWhereEmit((item) => item.stock == 0);

Update Operations #

Update Single Item

final wasUpdated = cubit.updateItemEmit(
  (item) => item.id == '123',  // Find item
  (item) => item.copyWith(     // Update it
    price: item.price * 0.9,   // 10% discount
  ),
);

Update Multiple Items

// Apply discount to all sale items
final count = cubit.updateWhereEmit(
  (item) => item.category == 'sale',
  (item) => item.copyWith(price: item.price * 0.8),
);
print('Updated $count items');

// Mark all as featured
cubit.updateWhereEmit(
  (item) => true,
  (item) => item.copyWith(isFeatured: true),
);

Other Operations #

Clear All Items

cubit.clearItems();

Reload from Server

cubit.reload();

Set Custom Items

// Replace all items with a new list
cubit.setItems(customProductList);

Access Current Items

final items = cubit.currentItems;
print('Total items: ${items.length}');

// Find specific item
final featured = items.where((item) => item.isFeatured).toList();

Real-World Examples #

Shopping Cart - Add to Cart

void addToCart(Product product) {
  cartCubit.addOrUpdateEmit(
    CartItem(product: product, quantity: 1),
  );
}

Todo App - Toggle Complete

void toggleTodo(String todoId) {
  todoCubit.updateItemEmit(
    (item) => item.id == todoId,
    (item) => item.copyWith(isCompleted: !item.isCompleted),
  );
}

Chat App - Delete Message

void deleteMessage(Message message) {
  chatCubit.removeItemEmit(message);
}

Inventory - Update Stock

void updateStock(String productId, int newStock) {
  inventoryCubit.updateItemEmit(
    (item) => item.id == productId,
    (item) => item.copyWith(stock: newStock),
  );
}

Bulk Operations

// Remove all completed tasks
taskCubit.removeWhereEmit((task) => task.isCompleted);

// Apply bulk discount
productCubit.updateWhereEmit(
  (product) => product.category == 'clearance',
  (product) => product.copyWith(price: product.price * 0.5),
);

⏰ Data Age & Expiration #

The dataAge feature allows automatic data invalidation and refresh when using the cubit as a global variable. This is perfect for scenarios where you want to keep the cubit alive across screen navigations but ensure data freshness.

Basic Usage #

// Create a global cubit with data expiration
final productsCubit = SmartPaginationCubit<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  dataAge: Duration(minutes: 5), // Data expires after 5 minutes
);

How It Works #

1. When data is successfully fetched, the lastFetchTime is recorded
2. When fetchPaginatedList() is called (e.g., when re-entering a screen), it checks if data has expired
3. If dataAge duration has passed since lastFetchTime, the cubit automatically:
   • Clears all cached data
   • Resets to initial state
   • Triggers a fresh data load

Timer Auto-Refresh: The timer resets on any data interaction (insert, update, remove, load more). This ensures active users don't experience unexpected data resets while using the list.

Available Properties #

// Check if data has expired
if (cubit.isDataExpired) {
  print('Data is stale');
}

// Get the last fetch timestamp
final lastFetch = cubit.lastFetchTime;

// Get the configured data age
final age = cubit.dataAge;

// Manually check and reset if expired (returns true if reset occurred)
final wasReset = cubit.checkAndResetIfExpired();

Accessing Expiration Info from State #

BlocBuilder<SmartPaginationCubit<Product>, SmartPaginationState<Product>>(
  builder: (context, state) {
    if (state is SmartPaginationLoaded<Product>) {
      // When the data was fetched
      final fetchedAt = state.fetchedAt;

      // When the data will expire (null if no dataAge configured)
      final expiresAt = state.dataExpiredAt;

      if (expiresAt != null) {
        final remaining = expiresAt.difference(DateTime.now());
        print('Data expires in ${remaining.inMinutes} minutes');
      }
    }
    return YourWidget();
  },
)

Use Case: Global Cubit with Auto-Refresh #

// In your dependency injection or global state
class AppState {
  static final productsCubit = SmartPaginationCubit<Product>(
    request: PaginationRequest(page: 1, pageSize: 20),
    provider: PaginationProvider.future(ApiService.fetchProducts),
    dataAge: Duration(minutes: 10), // Refresh data every 10 minutes
  );
}

// In your screen
class ProductsScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SmartPagination.listViewWithCubit(
      cubit: AppState.productsCubit,
      itemBuilder: (context, items, index) => ProductCard(items[index]),
    );
  }
}

// When user navigates to ProductsScreen after 10+ minutes,
// data will automatically refresh!

Configuration Options #

🛡️ Error Handling #

6 Error Widget Styles #

1. Material Design (Recommended for First Page Errors)

CustomErrorBuilder.material(
  context: context,
  error: error,
  onRetry: retry,
  title: 'Failed to Load Products',
  message: 'Please check your internet connection and try again.',
  icon: Icons.cloud_off,
  iconColor: Colors.blue,
  retryButtonText: 'Retry',
)

2. Compact (Recommended for Load More Errors)

CustomErrorBuilder.compact(
  context: context,
  error: error,
  onRetry: retry,
  message: 'Failed to load more items',
  backgroundColor: Colors.red[50],
  textColor: Colors.red[900],
)

3. Card Style

CustomErrorBuilder.card(
  context: context,
  error: error,
  onRetry: retry,
  title: 'Products Unavailable',
  message: 'We couldn\'t fetch the products at this time.',
  elevation: 4,
)

4. Minimal

CustomErrorBuilder.minimal(
  context: context,
  error: error,
  onRetry: retry,
  message: 'Something went wrong',
)

5. Snackbar

CustomErrorBuilder.snackbar(
  context: context,
  error: error,
  onRetry: retry,
  message: 'Failed to load data',
  backgroundColor: Colors.red,
)

6. Custom

CustomErrorBuilder.custom(
  context: context,
  error: error,
  onRetry: retry,
  builder: (context, error, retry) {
    return MyCustomErrorWidget(
      error: error,
      onRetry: retry,
    );
  },
)

Error Recovery Strategies #

The library supports multiple error recovery strategies:

1. Cached Data Fallback

Show offline/cached data when fresh data fails to load

2. Partial Data Display

Display whatever data loaded successfully before the error occurred

3. Alternative Source

Switch to a backup data source (e.g., backup server, CDN)

4. User-Initiated Recovery

Require user action to resolve (e.g., login, grant permissions)

5. Graceful Degradation

Continue with limited functionality in offline/error mode

See docs/ERROR_HANDLING.md and the example app for complete implementations.

Custom Exception Types #

Define your own exception types for better error handling:

class NetworkException implements Exception {
  final String message;
  NetworkException(this.message);

  @override
  String toString() => 'NetworkException: $message';
}

class TimeoutException implements Exception {
  final String message;
  TimeoutException(this.message);

  @override
  String toString() => 'TimeoutException: $message';
}

class ServerException implements Exception {
  final int statusCode;
  final String message;
  ServerException(this.statusCode, this.message);

  @override
  String toString() => 'ServerException($statusCode): $message';
}

// Use in error builders
firstPageErrorBuilder: (context, error, retry) {
  if (error is NetworkException) {
    return NetworkErrorWidget(onRetry: retry);
  } else if (error is TimeoutException) {
    return TimeoutErrorWidget(onRetry: retry);
  } else if (error is ServerException) {
    return ServerErrorWidget(statusCode: error.statusCode, onRetry: retry);
  }
  return CustomErrorBuilder.material(context: context, error: error, onRetry: retry);
}

Error Illustrations #

The library includes an ErrorImages helper for beautiful error illustrations:

CustomErrorBuilder.material(
  context: context,
  error: error,
  onRetry: retry,
  title: 'No Internet Connection',
  message: 'Please check your connection and try again',
  // Add custom image above the error
  customChild: ErrorImages.network(
    width: 200,
    height: 200,
    fallbackColor: Colors.orange,
  ),
)

Available images:

• ErrorImages.general() - General error
• ErrorImages.network() - Network/connectivity error
• ErrorImages.notFound() - 404 not found
• ErrorImages.serverError() - 500 server error
• ErrorImages.timeout() - Request timeout
• ErrorImages.auth() - Authentication error
• ErrorImages.offline() - Offline mode
• ErrorImages.empty() - Empty state
• ErrorImages.retry() - Retry icon
• ErrorImages.recovery() - Recovery icon
• ErrorImages.loadingError() - Load more error
• ErrorImages.custom() - Custom error

Features:

• Automatic fallback to icons if images fail to load
• Customizable width, height, and fallback colors
• Free illustration sources guide included

See docs/ERROR_IMAGES_SETUP.md for setup instructions.

🎨 View Types #

1. ListView #

Standard vertical or horizontal scrolling list.

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  itemBuilder: (context, items, index) {
    final product = items[index];
    return ListTile(
      leading: Image.network(product.imageUrl),
      title: Text(product.name),
      subtitle: Text('\$${product.price}'),
      trailing: Icon(Icons.arrow_forward_ios),
    );
  },
  separator: Divider(),
)

Properties:

• scrollDirection: Axis.vertical (default) or Axis.horizontal
• shrinkWrap: true to fit content
• reverse: true for bottom-to-top scrolling
• separatorBuilder: Add dividers between items

2. GridView #

Multi-column grid layout.

SmartPagination.gridViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 2,
    childAspectRatio: 0.75,
    crossAxisSpacing: 10,
    mainAxisSpacing: 10,
  ),
  itemBuilder: (context, items, index) {
    final product = items[index];
    return Card(
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Expanded(
            child: Image.network(
              product.imageUrl,
              fit: BoxFit.cover,
            ),
          ),
          Padding(
            padding: EdgeInsets.all(8),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  product.name,
                  style: TextStyle(fontWeight: FontWeight.bold),
                  maxLines: 1,
                  overflow: TextOverflow.ellipsis,
                ),
                SizedBox(height: 4),
                Text('\$${product.price}'),
              ],
            ),
          ),
        ],
      ),
    );
  },
)

3. Column (Non-scrollable) #

A non-scrollable column layout, useful when you want to embed the list inside another scroll view (e.g., SingleChildScrollView).

SingleChildScrollView(
  child: Column(
    children: [
      HeaderWidget(),
      SmartPagination.columnWithProvider<Product>(
        request: PaginationRequest(page: 1, pageSize: 5),
        provider: PaginationProvider.future(fetchProducts),
        itemBuilder: (context, items, index) => ProductTile(items[index]),
        separator: Divider(),
      ),
      FooterWidget(),
    ],
  ),
)

4. PageView #

Swipeable full-screen pages.

SmartPagination.pageViewWithCubit(
  cubit: cubit,
  itemBuilder: (context, items, index) {
    return Container(
      width: double.infinity,
      height: double.infinity,
      child: ProductDetailView(product: items[index]),
    );
  },
  scrollDirection: Axis.horizontal,
)

Use cases:

• Image carousels
• Onboarding flows
• Full-screen product views
• Story-style content

4. StaggeredGridView #

Pinterest-style masonry layout with varying item sizes.

SmartPagination.staggeredGridViewWithCubit(
  cubit: cubit,
  crossAxisCount: 2,
  itemBuilder: (context, items, index) {
    final product = items[index];
    return StaggeredGridTile.fit(
      crossAxisCellCount: 1,
      child: Card(
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Image.network(
              product.imageUrl,
              fit: BoxFit.cover,
            ),
            Padding(
              padding: EdgeInsets.all(8),
              child: Text(product.name),
            ),
          ],
        ),
      ),
    );
  },
)

Use cases:

• Pinterest-style galleries
• Mixed-size content
• Dynamic height items
• Photo galleries

5. ReorderableListView #

Drag-and-drop list reordering.

SmartPagination.reorderableListViewWithCubit(
  cubit: cubit,
  itemBuilder: (context, items, index) {
    return ListTile(
      key: ValueKey(items[index].id),
      leading: Icon(Icons.drag_handle),
      title: Text(items[index].name),
      subtitle: Text('Priority: ${index + 1}'),
    );
  },
  onReorder: (oldIndex, newIndex) {
    // Handle reordering logic
    if (newIndex > oldIndex) {
      newIndex -= 1;
    }
    final item = items.removeAt(oldIndex);
    items.insert(newIndex, item);
  },
)

Use cases:

• Task lists
• Priority management
• Playlist organization
• Custom ordering

6. Custom View Builder #

Complete control over the layout.

SmartPagination.withCubit(
  cubit: cubit,
  itemBuilderType: PaginateBuilderType.custom,
  customViewBuilder: (context, items, hasReachedEnd, fetchMore) {
    return Column(
      children: [
        // Your custom header
        Container(
          padding: EdgeInsets.all(16),
          child: Text('Found ${items.length} items'),
        ),

        // Your custom layout
        Expanded(
          child: YourCustomLayout(
            items: items,
            onLoadMore: fetchMore,
            isLastPage: hasReachedEnd,
          ),
        ),

        // Your custom footer
        if (!hasReachedEnd)
          TextButton(
            onPressed: fetchMore,
            child: Text('Load More'),
          ),
      ],
    );
  },
)

Use cases:

• Unique layouts
• Complex UIs
• Mixed view types
• Custom interactions

🚀 Advanced Usage #

Stream Support #

Real-time Updates (Single Stream)

SmartPagination.listViewWithProvider<Message>(
  request: PaginationRequest(page: 1, pageSize: 50),
  provider: PaginationProvider.stream(
    (request) => firestore
        .collection('messages')
        .orderBy('timestamp', descending: true)
        .limit(request.pageSize)
        .snapshots()
        .map((snapshot) => snapshot.docs.map((doc) => Message.fromDoc(doc)).toList()),
  ),
  itemBuilder: (context, items, index) {
    return MessageBubble(message: items[index]);
  },
)

Multiple Streams

Switch between different data streams:

class ProductsPage extends StatefulWidget {
  @override
  _ProductsPageState createState() => _ProductsPageState();
}

class _ProductsPageState extends State<ProductsPage> {
  String selectedStream = 'all';

  Stream<List<Product>> getStream(PaginationRequest request) {
    switch (selectedStream) {
      case 'featured':
        return apiService.featuredProductsStream(request);
      case 'sale':
        return apiService.saleProductsStream(request);
      default:
        return apiService.allProductsStream(request);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Products'),
        actions: [
          DropdownButton<String>(
            value: selectedStream,
            items: [
              DropdownMenuItem(value: 'all', child: Text('All')),
              DropdownMenuItem(value: 'featured', child: Text('Featured')),
              DropdownMenuItem(value: 'sale', child: Text('On Sale')),
            ],
            onChanged: (value) => setState(() => selectedStream = value!),
          ),
        ],
      ),
      body: SmartPagination.listViewWithProvider<Product>(
        key: ValueKey(selectedStream), // Force rebuild on stream change
        request: PaginationRequest(page: 1, pageSize: 20),
        provider: PaginationProvider.stream(getStream),
        itemBuilder: (context, items, index) => ProductCard(items[index]),
      ),
    );
  }
}

Merged Streams

Combine multiple streams into one:

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.mergeStreams(
    (request) => [
      apiService.regularProductsStream(request),
      apiService.featuredProductsStream(request),
      apiService.saleProductsStream(request),
    ],
  ),
  itemBuilder: (context, items, index) => ProductCard(items[index]),
)

External Cubit & State Management #

If you need to manage the SmartPaginationCubit externally (e.g., for dependency injection or sharing state), use the ...WithCubit named constructors:

• SmartPagination.listViewWithCubit
• SmartPagination.gridViewWithCubit
• SmartPagination.columnWithCubit
• SmartPagination.pageViewWithCubit
• SmartPagination.staggeredGridViewWithCubit
• SmartPagination.rowWithCubit
• SmartPagination.reorderableListViewWithCubit

class MyPage extends StatefulWidget {
  @override
  _MyPageState createState() => _MyPageState();
}

class _MyPageState extends State<MyPage> {
  late SmartPaginationCubit<Product> _cubit;

  @override
  void initState() {
    super.initState();
    _cubit = SmartPaginationCubit<Product>(
      request: PaginationRequest(page: 1, pageSize: 20),
      provider: PaginationProvider.future(fetchProducts),
    );
  }

  @override
  Widget build(BuildContext context) {
    return SmartPagination.listViewWithCubit<Product>(
      cubit: _cubit,
      itemBuilder: (context, items, index) => ProductCard(items[index]),
    );
  }

  @override
  void dispose() {
    _cubit.close();
    super.dispose();
  }
}

Scroll Control #

Programmatic scrolling to specific items or indices:

final controller = SmartPaginationController<Product>();

class ProductsPage extends StatefulWidget {
  @override
  _ProductsPageState createState() => _ProductsPageState();
}

class _ProductsPageState extends State<ProductsPage> {
  late SmartPaginationCubit<Product> cubit;

  @override
  void initState() {
    super.initState();
    cubit = SmartPaginationCubit<Product>(
      request: PaginationRequest(page: 1, pageSize: 20),
      provider: PaginationProvider.future(fetchProducts),
    )..controller = controller;
  }

  void scrollToProduct(Product product) {
    controller.scrollToItem(
      product,
      duration: Duration(milliseconds: 300),
      curve: Curves.easeInOut,
    );
  }

  void scrollToIndex(int index) {
    controller.scrollToIndex(
      index,
      duration: Duration(milliseconds: 300),
      curve: Curves.easeInOut,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Products'),
        actions: [
          IconButton(
            icon: Icon(Icons.arrow_upward),
            onPressed: () => scrollToIndex(0), // Scroll to top
          ),
        ],
      ),
      body: SmartPagination.withCubit(
        cubit: cubit,
        itemBuilder: (context, items, index) => ProductCard(items[index]),
      ),
    );
  }

  @override
  void dispose() {
    cubit.close();
    super.dispose();
  }
}

Before Build Hook #

Transform state before rendering:

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  itemBuilder: (context, items, index) => ProductCard(items[index]),

  // Sort items before rendering
  beforeBuild: (state) {
    if (state is SmartPaginationLoaded<Product>) {
      final sortedItems = state.items.toList()
        ..sort((a, b) => a.price.compareTo(b.price));
      return state.copyWith(items: sortedItems);
    }
    return state;
  },
)

List Builder #

Transform items in the cubit before emission:

SmartPaginationCubit<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),

  // Remove duplicates
  listBuilder: (items) {
    return items.toSet().toList();
  },
)

Callbacks #

React to pagination events:

SmartPaginationCubit<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),

  onInsertionCallback: (items) {
    print('Loaded ${items.length} new items');
    analytics.logEvent('items_loaded', {'count': items.length});
  },

  onReachedEnd: () {
    print('Reached end of pagination');
    showSnackBar('No more items to load');
  },

  onClear: () {
    print('Pagination list cleared');
  },
)

Pull to Refresh #

Add swipe-down-to-refresh functionality:

final refreshListener = SmartPaginationRefreshedChangeListener();

class ProductsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return RefreshIndicator(
      onRefresh: () async {
        refreshListener.refreshed = true;
        await Future.delayed(Duration(seconds: 1));
      },
      child: SmartPagination.listViewWithProvider<Product>(
        request: PaginationRequest(page: 1, pageSize: 20),
        provider: PaginationProvider.future(fetchProducts),
        refreshListener: refreshListener,
        itemBuilder: (context, items, index) => ProductCard(items[index]),
      ),
    );
  }
}

Memory Management #

Optimize memory usage for large datasets:

SmartPaginationCubit<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),

  // Keep only 5 pages in memory (100 items with pageSize=20)
  // Older pages are automatically removed
  maxPagesInMemory: 5,
)

Custom Loading States #

Customize loading indicators for different states:

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  itemBuilder: (context, items, index) => ProductCard(items[index]),

  // Full-screen loading for first page
  firstPageLoadingBuilder: (context) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          CircularProgressIndicator(),
          SizedBox(height: 16),
          Text('Loading products...'),
        ],
      ),
    );
  },

  // Bottom loading for pagination
  loadMoreLoadingBuilder: (context) {
    return Container(
      padding: EdgeInsets.all(16),
      alignment: Alignment.center,
      child: Row(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          SizedBox(
            width: 20,
            height: 20,
            child: CircularProgressIndicator(strokeWidth: 2),
          ),
          SizedBox(width: 12),
          Text('Loading more...'),
        ],
      ),
    );
  },
)

Custom Empty States #

Show custom UI when no data is available:

SmartPagination.listViewWithProvider<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  itemBuilder: (context, items, index) => ProductCard(items[index]),

  firstPageEmptyBuilder: (context) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Icon(
            Icons.shopping_basket_outlined,
            size: 100,
            color: Colors.grey,
          ),
          SizedBox(height: 16),
          Text(
            'No Products Found',
            style: TextStyle(
              fontSize: 20,
              fontWeight: FontWeight.bold,
            ),
          ),
          SizedBox(height: 8),
          Text(
            'Try adjusting your filters',
            style: TextStyle(color: Colors.grey),
          ),
        ],
      ),
    );
  },
)

Cursor-Based Pagination #

Efficient pagination for large datasets:

// Your API response model
class PaginatedResponse<T> {
  final List<T> items;
  final String? nextCursor;
  final bool hasMore;

  PaginatedResponse({
    required this.items,
    this.nextCursor,
    required this.hasMore,
  });
}

// Use cursor in pagination
class ProductsPage extends StatefulWidget {
  @override
  _ProductsPageState createState() => _ProductsPageState();
}

class _ProductsPageState extends State<ProductsPage> {
  String? nextCursor;

  Future<List<Product>> fetchProducts(PaginationRequest request) async {
    final response = await apiService.fetchProductsCursor(
      cursor: nextCursor,
      limit: request.pageSize,
    );

    nextCursor = response.nextCursor;
    return response.items;
  }

  @override
  Widget build(BuildContext context) {
    return SmartPagination.listViewWithProvider<Product>(
      request: PaginationRequest(page: 1, pageSize: 20),
      provider: PaginationProvider.future(fetchProducts),
      itemBuilder: (context, items, index) => ProductCard(items[index]),
    );
  }
}

🎨 Example App #

The library includes a comprehensive example app with 29 demonstration screens covering every feature.

Running the Example #

cd example
flutter pub get
flutter run

📱 All Example Screens with Screenshots #

🎯 Basic Pagination Examples #

1. Basic ListView

Simple paginated product list with automatic loading.

Features: Automatic pagination, loading indicators, scroll-to-load

Code: basic_listview_screen.dart

2. GridView Pagination

Product grid with 2 columns and pagination.

Features: GridView layout, configurable columns, responsive grid

Code: gridview_screen.dart

3. Retry Mechanism

Automatic retry with exponential backoff.

Features: Auto-retry, exponential backoff, configurable attempts

Code: retry_demo_screen.dart

4. Filter & Search

Real-time search and filtering with pagination.

Features: Server-side filtering, search as you type, filter persistence

Code: filter_search_screen.dart

5. Pull to Refresh

Swipe down to refresh functionality.

Features: Pull-to-refresh, refresh indicators, state reset

Code: pull_to_refresh_screen.dart

📡 Stream Examples #

6. Single Stream

Real-time updates from a single data stream.

Features: Real-time updates, WebSocket/Firestore integration, auto-sync

Code: single_stream_screen.dart

7. Multi Stream

Switch between different data streams dynamically.

Features: Stream switching, multiple data sources, smooth transitions

Code: multi_stream_screen.dart

8. Merged Streams

Combine multiple streams into one unified list.

Features: Stream merging, unified data, concurrent updates

Code: merged_streams_screen.dart

⚙️ Advanced Examples #

9. Cursor Pagination

Efficient cursor-based pagination for large datasets.

Features: Cursor-based pagination, efficient queries, no page skipping

Code: cursor_pagination_screen.dart

10. Horizontal Scroll

Horizontal scrolling paginated list.

Features: Horizontal orientation, swipe navigation, carousel-style

Code: horizontal_list_screen.dart

11. PageView

Swipeable full-screen pages with pagination.

Features: Full-screen pages, swipe gestures, page indicators

Code: page_view_screen.dart

12. Staggered Grid

Pinterest-style masonry layout.

Features: Masonry layout, variable heights, dynamic positioning

Code: staggered_grid_screen.dart

13. Custom States

Custom loading, empty, and error states.

Features: Custom UI for all states, branded loading, custom animations

Code: custom_states_screen.dart

14. Scroll Control

Programmatic scrolling to specific items or indices.

Features: Scroll to item, scroll to index, smooth animations

Code: scroll_control_screen.dart

15. beforeBuild Hook

Transform state before rendering.

Features: State transformation, sorting, filtering before render

Code: before_build_hook_screen.dart

16. hasReachedEnd

Detect when pagination reaches the end.

Features: End detection, custom end message, callbacks

Code: has_reached_end_screen.dart

17. Custom View Builder

Complete control over the layout.

Features: Fully custom layouts, mixed views, complex UIs

Code: custom_view_builder_screen.dart

18. Reorderable List

Drag and drop to reorder items.

Features: Drag-and-drop, reorder callbacks, visual feedback

Code: reorderable_list_screen.dart

19. State Separation

Different UI for first page vs load more states.

Features: Separate first page/load more UI, different error handling

Code: state_separation_screen.dart

20. Smart Preloading

Configurable preload threshold.

Features: Preload before end, configurable threshold, smooth experience

Code: smart_preloading_screen.dart

21. Custom Error Handling

All error widget styles demonstration.

Features: All 6 error styles, custom error types, retry mechanisms

Code: custom_error_handling_screen.dart

22. Data Operations

Programmatic data manipulation (add, remove, update, clear).

Features: Insert items, remove items, update items, clear all, reload, set items

Code: data_operations_screen.dart

🛡️ Error Handling Examples #

23. Basic Error Handling

Simple error display with retry button.

Features: Simple retry, error counter, success after N attempts

Code: basic_error_example.dart

24. Network Errors

Different network error types (timeout, 404, 500, etc.).

Features: Custom exceptions, context-aware errors, appropriate icons

Code: network_errors_example.dart

25. Retry Patterns

Manual, auto, exponential backoff, limited retries.

Features: 4 retry strategies, countdown timers, retry limits

Code: retry_patterns_example.dart

26. Custom Error Widgets

All 6 pre-built error widget styles.

Features: Material, Compact, Card, Minimal, Snackbar, Custom styles

Code: custom_error_widgets_example.dart

27. Error Recovery

Cached data, partial data, fallback strategies.

Features: 4 recovery strategies, offline mode, data persistence

Code: error_recovery_example.dart

28. Graceful Degradation

Offline mode, placeholders, limited features.

Features: 3 degradation strategies, offline UI, skeleton screens

Code: graceful_degradation_example.dart

29. Load More Errors

Handle errors while loading additional pages.

Features: 3 load-more patterns, inline errors, dismissible banners

Code: load_more_errors_example.dart

📸 Adding Screenshots #

To capture screenshots for the examples:

1. Run the example app
2. Navigate to each screen
3. Take screenshots (recommended: 1080x2400px)
4. Save to screenshots/ directory following naming convention

See screenshots/README.md for detailed instructions.

📚 API Reference #

SmartPagination.withProvider #

Low-level widget for complete control.

SmartPagination.withProvider<T>({
  // Data source
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,

  // View type
  PaginateBuilderType itemBuilderType = PaginateBuilderType.listView,

  // Custom view builder
  Widget Function(
    BuildContext context,
    List<T> items,
    bool hasReachedEnd,
    VoidCallback fetchMore,
  )? customViewBuilder,

  // All other parameters same as SmartPagination.listView
})

SmartPagination.withCubit #

Use with your own cubit instance for full control.

SmartPagination.withCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  required PaginateBuilderType itemBuilderType,
  // ... other parameters
})

SmartPagination.columnWithProvider #

Creates a pagination widget as a Column layout (non-scrollable).

SmartPagination.columnWithProvider<T>({
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

SmartPagination.columnWithCubit #

Creates a pagination widget as a Column layout (non-scrollable) with an external Cubit.

SmartPagination.columnWithCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

SmartPagination.gridViewWithProvider #

Grid layout with pagination.

SmartPagination.gridViewWithProvider<T>({
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  required SliverGridDelegate gridDelegate,
  // ... other parameters
})

SmartPagination.gridViewWithCubit #

Grid layout with pagination with an external Cubit.

SmartPagination.gridViewWithCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  required SliverGridDelegate gridDelegate,
  // ... other parameters
})

SmartPagination.listViewWithProvider #

The easiest way to create a paginated list.

SmartPagination.listViewWithProvider<T>({
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

SmartPagination.listViewWithCubit #

ListView layout with pagination with an external Cubit.

SmartPagination.listViewWithCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

SmartPagination.reorderableListViewWithProvider #

Reorderable list layout with pagination.

SmartPagination.reorderableListViewWithProvider<T>({
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  required void Function(int oldIndex, int newIndex) onReorder,
  // ... other parameters
})

SmartPagination.reorderableListViewWithCubit #

Reorderable list layout with pagination with an external Cubit.

SmartPagination.reorderableListViewWithCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  required void Function(int oldIndex, int newIndex) onReorder,
  // ... other parameters
})

SmartPagination.pageViewWithProvider #

PageView layout with pagination.

SmartPagination.pageViewWithProvider<T>({
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

SmartPagination.pageViewWithCubit #

PageView layout with pagination with an external Cubit.

SmartPagination.pageViewWithCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

SmartPagination.staggeredGridViewWithProvider #

StaggeredGridView layout with pagination.

SmartPagination.staggeredGridViewWithProvider<T>({
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required StaggeredGridTile Function(BuildContext, List<T>, int) itemBuilder,
  required int crossAxisCount,
  // ... other parameters
})

SmartPagination.staggeredGridViewWithCubit #

StaggeredGridView layout with pagination with an external Cubit.

SmartPagination.staggeredGridViewWithCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required StaggeredGridTile Function(BuildContext, List<T>, int) itemBuilder,
  required int crossAxisCount,
  // ... other parameters
})

SmartPagination.rowWithProvider #

Row layout (horizontal non-scrollable) with pagination.

SmartPagination.rowWithProvider<T>({
  required PaginationRequest request,
  required PaginationProvider<T> provider,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

SmartPagination.rowWithCubit #

Row layout (horizontal non-scrollable) with pagination with an external Cubit.

SmartPagination.rowWithCubit<T>({
  required SmartPaginationCubit<T> cubit,
  required Widget Function(BuildContext, List<T>, int) itemBuilder,
  // ... other parameters
})

Configuration Fields #

PaginationProvider #

Defines how data is fetched.

// Future-based (REST APIs)
PaginationProvider.future(
  Future<List<T>> Function(PaginationRequest request) provider,
)

// Stream-based (Real-time)
PaginationProvider.stream(
  Stream<List<T>> Function(PaginationRequest request) provider,
)

// Merged streams
PaginationProvider.mergeStreams(
  List<Stream<List<T>>> Function(PaginationRequest request) providers,
)

PaginationRequest #

Request configuration.

const PaginationRequest({
  required int page,              // Current page number (1-indexed)
  required int pageSize,          // Number of items per page
  Map<String, dynamic>? filters,  // Optional filters for server-side filtering
})

RetryConfig #

Configure automatic retry behavior.

RetryConfig({
  int maxAttempts = 3,                        // Max retry attempts
  Duration initialDelay = Duration(seconds: 1), // Initial retry delay
  Duration maxDelay = Duration(seconds: 10),    // Maximum retry delay
  Duration? timeoutDuration,                    // Request timeout
  List<Duration>? retryDelays,                  // Custom delays per attempt
  bool Function(Exception)? shouldRetry,        // Custom retry condition
})

CustomErrorBuilder #

Pre-built error widget styles.

// Material Design
CustomErrorBuilder.material({
  required BuildContext context,
  required Exception error,
  required VoidCallback onRetry,
  String? title,
  String? message,
  IconData? icon,
  Color? iconColor,
  String? retryButtonText,
})

// Compact inline
CustomErrorBuilder.compact({
  required BuildContext context,
  required Exception error,
  required VoidCallback onRetry,
  String? message,
  Color? backgroundColor,
  Color? textColor,
})

// Card style
CustomErrorBuilder.card({
  required BuildContext context,
  required Exception error,
  required VoidCallback onRetry,
  String? title,
  String? message,
  double? elevation,
})

// Minimal
CustomErrorBuilder.minimal({
  required BuildContext context,
  required Exception error,
  required VoidCallback onRetry,
  String? message,
})

// Snackbar
CustomErrorBuilder.snackbar({
  required BuildContext context,
  required Exception error,
  required VoidCallback onRetry,
  String? message,
  Color? backgroundColor,
})

// Custom
CustomErrorBuilder.custom({
  required BuildContext context,
  required Exception error,
  required VoidCallback onRetry,
  required Widget Function(BuildContext, Exception, VoidCallback) builder,
})

ErrorImages #

Helper for error illustrations with automatic icon fallback.

ErrorImages.general({double width, double height, Color? fallbackColor})
ErrorImages.network({double width, double height, Color? fallbackColor})
ErrorImages.notFound({double width, double height, Color? fallbackColor})
ErrorImages.server({double width, double height, Color? fallbackColor})
ErrorImages.timeout({double width, double height, Color? fallbackColor})
ErrorImages.auth({double width, double height, Color? fallbackColor})
ErrorImages.offline({double width, double height, Color? fallbackColor})
ErrorImages.empty({double width, double height, Color? fallbackColor})
ErrorImages.retry({double width, double height, Color? fallbackColor})
ErrorImages.recovery({double width, double height, Color? fallbackColor})
ErrorImages.loading({double width, double height, Color? fallbackColor})
ErrorImages.custom({double width, double height, Color? fallbackColor})

SmartPaginationCubit #

Low-level BLoC for advanced use cases.

class SmartPaginationCubit<T> extends Cubit<SmartPaginationState<T>> {
  SmartPaginationCubit({
    required PaginationRequest request,
    required PaginationProvider<T> provider,
    RetryConfig? retryConfig,
    int? maxPagesInMemory,
    List<T> Function(List<T>)? listBuilder,
    void Function(List<T>)? onInsertionCallback,
    VoidCallback? onClear,
    VoidCallback? onReachedEnd,
    Logger? logger,
    Duration? dataAge,                // NEW: Auto-expire data after this duration
  });

  // Properties
  List<T> get currentItems;           // Get current items (read-only)
  bool get didFetch;                  // Whether data has been fetched
  Duration? get dataAge;              // Get configured data age duration
  DateTime? get lastFetchTime;        // Get timestamp of last successful fetch
  bool get isDataExpired;             // Check if data has expired

  // Pagination Methods
  void fetchPaginatedList();          // Fetch next page (auto-checks expiration)
  void refreshPaginatedList();        // Refresh from beginning
  void reload();                      // Alias for refreshPaginatedList
  bool checkAndResetIfExpired();      // Check and reset if data expired

  // Insert Operations
  void insertEmit(T item, {int index = 0});           // Insert single item
  void insertAllEmit(List<T> items, {int index = 0}); // Insert multiple items
  void addOrUpdateEmit(T item, {int index = 0});      // Add or update item

  // Remove Operations
  bool removeItemEmit(T item);                        // Remove by item
  T? removeAtEmit(int index);                         // Remove by index
  int removeWhereEmit(bool Function(T) test);         // Remove by condition

  // Update Operations
  bool updateItemEmit(
    bool Function(T) matcher,
    T Function(T) updater,
  );                                                   // Update single item
  int updateWhereEmit(
    bool Function(T) matcher,
    T Function(T) updater,
  );                                                   // Update multiple items

  // Other Operations
  void clearItems();                                   // Clear all items
  void setItems(List<T> items);                        // Set custom items
  void filterPaginatedList(bool Function(T)? filter); // Filter items
}

SmartPaginationState #

BLoC states.

// Initial state
class SmartPaginationInitial<T> extends SmartPaginationState<T>

// Loading first page
class SmartPaginationLoading<T> extends SmartPaginationState<T>

// Data loaded
class SmartPaginationLoaded<T> extends SmartPaginationState<T> {
  final List<T> items;
  final bool hasReachedEnd;
  final bool isLoadingMore;
  final Exception? loadMoreError;
  final DateTime? fetchedAt;        // When data was fetched
  final DateTime? dataExpiredAt;    // When data will expire
}

// First page error
class SmartPaginationError<T> extends SmartPaginationState<T> {
  final Exception exception;
}

// Empty state
class SmartPaginationEmpty<T> extends SmartPaginationState<T>

🎯 Best Practices #

1. Reuse Cubits for Performance #

Create the cubit once and reuse it:

// ❌ Bad - Creates new cubit on every build
Widget build(BuildContext context) {
  return SmartPagination.listViewWithProvider<Product>(
    request: PaginationRequest(page: 1, pageSize: 20),
    provider: PaginationProvider.future(fetchProducts),
    itemBuilder: (context, items, index) => ProductCard(items[index]),
  );
}

// ✅ Good - Reuse cubit instance
class ProductsPage extends StatefulWidget {
  @override
  _ProductsPageState createState() => _ProductsPageState();
}

class _ProductsPageState extends State<ProductsPage> {
  late SmartPaginationCubit<Product> cubit;

  @override
  void initState() {
    super.initState();
    cubit = SmartPaginationCubit<Product>(
      request: PaginationRequest(page: 1, pageSize: 20),
      provider: PaginationProvider.future(fetchProducts),
    );
  }

  @override
  Widget build(BuildContext context) {
    return SmartPagination.withCubit(
      cubit: cubit,
      itemBuilder: (context, items, index) => ProductCard(items[index]),
    );
  }

  @override
  void dispose() {
    cubit.close();
    super.dispose();
  }
}

2. Optimize Memory Usage #

Set maxPagesInMemory based on your item size:

SmartPaginationCubit<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  maxPagesInMemory: 5, // Keeps ~100 items in memory
)

3. Always Provide Error Builders #

Better user experience with custom error handling:

SmartPagination.listView<Product>(
  // ... other properties

  firstPageErrorBuilder: (context, error, retry) {
    return CustomErrorBuilder.material(
      context: context,
      error: error,
      onRetry: retry,
      title: 'Oops!',
      message: 'Something went wrong. Please try again.',
    );
  },

  loadMoreErrorBuilder: (context, error, retry) {
    return CustomErrorBuilder.compact(
      context: context,
      error: error,
      onRetry: retry,
    );
  },
)

4. Use State Separation #

Different UI for first page vs load more:

// Different loading indicators
firstPageLoadingBuilder: (context) => FullScreenLoader(),
loadMoreLoadingBuilder: (context) => BottomLoader(),

// Different error widgets
firstPageErrorBuilder: (context, error, retry) => FullScreenError(),
loadMoreErrorBuilder: (context, error, retry) => InlineError(),

5. Smart Preloading Configuration #

Adjust based on your use case:

// Fast scrolling content (e.g., chat)
invisibleItemsThreshold: 5,

// Slow scrolling content (e.g., product catalog)
invisibleItemsThreshold: 2,

// On-demand loading only
invisibleItemsThreshold: 0,

6. Use listBuilder for Transformations #

Prefer listBuilder over beforeBuild for performance:

// ✅ Good - Transforms in cubit before emission
SmartPaginationCubit<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  listBuilder: (items) => items.toSet().toList(), // Remove duplicates
)

// ⚠️ Less efficient - Transforms on every build
SmartPagination.listView<Product>(
  request: PaginationRequest(page: 1, pageSize: 20),
  provider: PaginationProvider.future(fetchProducts),
  beforeBuild: (state) {
    // Runs on every build
  },
  itemBuilder: (context, items, index) => ProductCard(items[index]),
)

7. Error Images with Fallback #

Always use fallback to ensure content displays:

ErrorImages.network(
  width: 200,
  height: 200,
  fallbackColor: Colors.orange, // Shows icon if image fails
)

8. Testing with Mock Data #

Create mock providers for predictable tests:

// Mock provider for testing
final mockProvider = PaginationProvider.future(
  (request) async {
    await Future.delayed(Duration(milliseconds: 500));
    return List.generate(
      request.pageSize,
      (i) => Product(
        id: '${request.page}-$i',
        name: 'Product ${request.page}-$i',
      ),
    );
  },
);

// Use in tests
testWidgets('displays products', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      home: SmartPagination.listView<Product>(
        request: PaginationRequest(page: 1, pageSize: 20),
        provider: mockProvider,
        itemBuilder: (context, items, index) {
          return Text(items[index].name);
        },
      ),
    ),
  );

  await tester.pumpAndSettle();
  expect(find.text('Product 1-0'), findsOneWidget);
});

📖 Documentation #

• Error Handling Guide: docs/ERROR_HANDLING.md
• Error Images Setup: docs/ERROR_IMAGES_SETUP.md
• Changelog: CHANGELOG.md
• License: LICENSE

📄 License #

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

MIT License

Copyright (c) 2024 Genius Systems

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 Acknowledgments #

• flutter_bloc - State management (pub.flutter-io.cn/packages/flutter_bloc)
• scrollview_observer - Scroll control (pub.flutter-io.cn/packages/scrollview_observer)
• flutter_staggered_grid_view - Staggered layouts (pub.flutter-io.cn/packages/flutter_staggered_grid_view)
• Inspired by Flutter pagination best practices

🌟 Features Comparison #

💡 Use Cases #

E-Commerce Apps #

• Product catalogs with grid/list views
• Search and filter products
• Categorized product listings
• Order history pagination

Social Media #

• News feeds with real-time updates
• User profiles and followers lists
• Comments and replies threading
• Media galleries (photos, videos)

Content Apps #

• Article listings
• Video streaming libraries
• Podcast episodes
• News aggregators

Business Apps #

• Transaction histories
• Customer lists
• Invoice management
• Report listings

Chat Apps #

• Message history pagination
• Contact lists
• Channel/group listings
• File/media sharing logs

Example Code #

• Basic Examples
• Stream Examples
• Error Examples
• Advanced Examples