pagination_grid_view #

A Flutter grid view widget with built-in pagination support. Automatically loads more items when scrolling near the bottom.

Features #

📱 Auto Pagination - Loads more data automatically when scrolling
🔄 Pull to Refresh - Built-in refresh support
🎨 Customizable - Loading indicators, empty states, error widgets
📐 Responsive - Fixed columns or max extent mode
⚡ Zero Dependencies - Pure Flutter
🎯 Type Safe - Generic support for any data type
🚀 Easy to Use - Simple, intuitive API

Installation #

dependencies:
  pagination_grid_view: ^1.0.1

Quick Start #

import 'package:pagination_grid_view/pagination_grid_view.dart';

PaginationGridView<Product>(
  items: products,
  onLoadMore: () async {
    final newProducts = await fetchMoreProducts();
    setState(() => products.addAll(newProducts));
  },
  itemBuilder: (context, product, index) => ProductCard(product),
  crossAxisCount: 2,
  hasMoreData: hasMoreProducts,
)

Usage Examples #

1. Basic Grid with 2 Columns #

PaginationGridView<String>(
  items: items,
  onLoadMore: () async {
    await Future.delayed(Duration(seconds: 1));
    setState(() {
      items.addAll(List.generate(10, (i) => 'Item ${items.length + i}'));
    });
  },
  itemBuilder: (context, item, index) => Card(
    child: Center(child: Text(item)),
  ),
  crossAxisCount: 2,
  hasMoreData: items.length < 100,
)

2. Image Gallery (3 Columns) #

PaginationGridView<ImageData>(
  items: images,
  onLoadMore: loadMoreImages,
  itemBuilder: (context, image, index) => InkWell(
    onTap: () => viewImage(image),
    child: Image.network(
      image.url,
      fit: BoxFit.cover,
    ),
  ),
  crossAxisCount: 3,
  childAspectRatio: 1.0,
  crossAxisSpacing: 4,
  mainAxisSpacing: 4,
  hasMoreData: hasMoreImages,
  padding: EdgeInsets.all(4),
)

3. Product Grid with Pull-to-Refresh #

PaginationGridView<Product>(
  items: products,
  onLoadMore: () async {
    final newProducts = await api.fetchProducts(page: currentPage);
    setState(() {
      products.addAll(newProducts);
      currentPage++;
    });
  },
  onRefresh: () async {
    final freshProducts = await api.fetchProducts(page: 1);
    setState(() {
      products = freshProducts;
      currentPage = 2;
    });
  },
  itemBuilder: (context, product, index) => ProductCard(
    product: product,
    onTap: () => Navigator.push(...),
  ),
  crossAxisCount: 2,
  hasMoreData: currentPage <= totalPages,
  enablePullToRefresh: true,
)

4. Responsive Grid (Max Extent) #

Automatically adjusts column count based on screen width:

PaginationGridView.extent(
  items: products,
  onLoadMore: loadMore,
  itemBuilder: (context, product, index) => ProductCard(product),
  maxCrossAxisExtent: 200, // Max width per item
  hasMoreData: hasMore,
)

5. Custom Loading & Empty States #

PaginationGridView<Item>(
  items: items,
  onLoadMore: loadMore,
  itemBuilder: (context, item, index) => ItemCard(item),
  crossAxisCount: 2,
  hasMoreData: hasMore,
  isLoading: isLoadingInitial,

  // Custom loading indicator
  loadingWidget: Column(
    mainAxisAlignment: MainAxisAlignment.center,
    children: [
      CircularProgressIndicator(color: Colors.purple),
      SizedBox(height: 16),
      Text('Loading awesome content...'),
    ],
  ),

  // Custom empty state
  emptyWidget: Column(
    mainAxisAlignment: MainAxisAlignment.center,
    children: [
      Icon(Icons.search_off, size: 64, color: Colors.grey),
      SizedBox(height: 16),
      Text('No items found'),
      SizedBox(height: 8),
      ElevatedButton(
        onPressed: () => reload(),
        child: Text('Reload'),
      ),
    ],
  ),
)

6. With Error Handling #

PaginationGridView<Product>(
  items: products,
  onLoadMore: () async {
    try {
      final newProducts = await api.fetchProducts();
      setState(() {
        products.addAll(newProducts);
        hasError = false;
      });
    } catch (e) {
      setState(() => hasError = true);
    }
  },
  itemBuilder: (context, product, index) => ProductCard(product),
  crossAxisCount: 2,
  hasMoreData: hasMore,
  hasError: hasError,
  errorWidget: Column(
    mainAxisAlignment: MainAxisAlignment.center,
    children: [
      Icon(Icons.error_outline, size: 64, color: Colors.red),
      SizedBox(height: 16),
      Text('Failed to load products'),
      TextButton(
        onPressed: () => retry(),
        child: Text('Retry'),
      ),
    ],
  ),
)

7. Pinterest-Style (Different Aspect Ratios) #

// Use staggered grid package for variable heights
// Or use fixed aspect ratios:
PaginationGridView<Pin>(
  items: pins,
  onLoadMore: loadMore,
  itemBuilder: (context, pin, index) => PinCard(pin),
  crossAxisCount: 2,
  childAspectRatio: 0.7, // Taller items
  hasMoreData: hasMore,
)

API Reference #