Pagination

What Is Pagination?

Pagination is the process of dividing a large dataset into smaller chunks (pages) that are loaded incrementally. It's essential for:

Performance – Loading all data at once can be slow and memory-intensive
UX – Users don't want to wait for thousands of items to load
Bandwidth – Reduces data usage by loading only what's needed
Scalability – Works with APIs that have rate limits

🎯 The Problem Pagination Solves

Imagine an API that returns 10,000 users. Loading all of them at once would take several seconds, use lots of memory, and provide a poor user experience. Pagination solves this by loading 20 users at a time , with the option to load more when needed.

Pagination Strategies

There are three main pagination strategies used in Flutter apps:

♾️

Infinite Scroll

Load more data as the user scrolls down

📄

Page-Based

Navigate between pages (Next/Previous buttons)

🔢

Explicit "Load More" button at the bottom

API Pagination Patterns

Different APIs use different pagination patterns. Here are the most common:

Pattern 1: Page & Limit (Query Parameters)



         // Most common pattern
        
        GET /api/users?page=2&limit=20
        
         // Response includes pagination metadata
        
        {
        
         "data"
        
        : [...],
        
         "pagination"
        
        : {
        
         "currentPage"
        
        : 2,
        
         "totalPages"
        
        : 10,
        
         "totalItems"
        
        : 200,
        
         "itemsPerPage"
        
        : 20
    }
  }

Pattern 2: Offset & Limit



         // Good for databases with offset support
        
        GET /api/users?offset=20&limit=20
        
         // Response (similar to page-based)
        
        {
        
         "data"
        
        : [...],
        
         "total"
        
        : 200
  }

Pattern 3: Cursor-Based (Keyset)



         // More efficient for large datasets
        
        GET /api/users?after=abc123&limit=20
        
         // Response includes cursor for next page
        
        {
        
         "data"
        
        : [...],
        
         "nextCursor"
        
        : "def456",
        
         "hasMore"
        
        : true
  }

Implementing Infinite Scroll

Infinite scroll is the most common pagination pattern in mobile apps. Here's how to implement it using a ScrollController and ListView.builder .

        lib/pagination_service.dart – API Service with Pagination
       
import 'dart:convert';

import 'package:http/http.dart' as http;

class PaginationService {
  final http.Client client;

  static const int pageSize = 20;

  PaginationService({http.Client? client}) : client = client ?? http.Client();

  Future<Map<String, dynamic>> fetchPage(int page) async {
    final response = await client.get(
      Uri.parse(
        'https://jsonplaceholder.typicode.com/posts?_page=$page&_limit=$pageSize',
      ),
      headers: {'Accept': 'application/json'},
    );

    if (response.statusCode == 200) {
      final List<dynamic> data = jsonDecode(response.body);

      // Note: JSONPlaceholder doesn't return pagination metadata

      // In a real API, you'd parse the metadata from headers or body

      return {
        'data': data,

        'hasMore': data.length == pageSize,

        // Simple heuristic
      };
    } else {
      throw Exception('Failed to load page $page');
    }
  }
}

        lib/infinite_scroll_screen.dart – Infinite Scroll UI
       
import 'package:flutter/material.dart';

import 'pagination_service.dart';

class InfiniteScrollScreen extends StatefulWidget {
  @override
  State<InfiniteScrollScreen> createState() => _InfiniteScrollScreenState();
}

class _InfiniteScrollScreenState extends State<InfiniteScrollScreen> {
  final PaginationService _service = PaginationService();

  final ScrollController _scrollController = ScrollController();

  List<dynamic> _items = [];

  int _currentPage = 1;

  bool _isLoading = false;

  bool _hasMore = true;

  bool _hasError = false;
  String? _errorMessage;

  @override
  void initState() {
    super.initState();
    _loadMore();
    _scrollController.addListener(_onScroll);
  }

  @override
  void dispose() {
    _scrollController.dispose();

    super.dispose();
  }

  void _onScroll() {
    if (_scrollController.position.pixels >=
        _scrollController.position.maxScrollExtent - 200) {
      _loadMore();
    }
  }

  Future<void> _loadMore() async {
    if (_isLoading || !_hasMore) return;

    setState(() {
      _isLoading = true;
      _hasError = false;
      _errorMessage = null;
    });

    try {
      final result = await _service.fetchPage(_currentPage);

      final newItems = result['data'] as List<dynamic>;

      final hasMore = result['hasMore'] as bool;

      setState(() {
        _items.addAll(newItems);
        _hasMore = hasMore;
        _currentPage++;
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _isLoading = false;
        _hasError = true;
        _errorMessage = e.toString();
      });
    }
  }

  void _retry() {
    _loadMore();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Infinite Scroll'), centerTitle: true),
      body: Column(
        children: [
          Expanded(
            child: _items.isEmpty && !_isLoading
                ? Center(
                    child: _hasError
                        ? Column(
                            mainAxisAlignment: MainAxisAlignment.center,
                            children: [
                              Icon(Icons.error, size: 64, color: Colors.red),
                              SizedBox(height: 16),
                              Text(_errorMessage ?? 'Failed to load data'),
                              SizedBox(height: 16),
                              ElevatedButton(
                                onPressed: _retry,
                                child: Text('Retry'),
                              ),
                            ],
                          )
                        : Text('No items to display'),
                  )
                : ListView.builder(
                    controller: _scrollController,
                    itemCount: _items.length + (_hasMore ? 1 : 0),
                    itemBuilder: (context, index) {
                      // Show loading indicator at the end

                      if (index == _items.length) {
                        return Padding(
                          padding: EdgeInsets.symmetric(vertical: 16),
                          child: Center(child: CircularProgressIndicator()),
                        );
                      }

                      final item = _items[index];

                      return Card(
                        margin: EdgeInsets.symmetric(
                          horizontal: 16,
                          vertical: 4,
                        ),
                        child: ListTile(
                          title: Text(item['title'] ?? 'No title'),
                          subtitle: Text(item['body'] ?? 'No body'),
                          leading: CircleAvatar(
                            child: Text((index + 1).toString()),
                          ),
                        ),
                      );
                    },
                  ),
          ),

          // Error banner at bottom
          if (_hasError && _items.isNotEmpty)
            Container(
              padding: EdgeInsets.all(12),
              color: Colors.red.shade50,
              child: Row(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Icon(Icons.warning, color: Colors.red),
                  SizedBox(width: 8),
                  Expanded(
                    child: Text(
                      _errorMessage ?? 'Failed to load more items',
                      style: TextStyle(color: Colors.red.shade700),
                    ),
                  ),
                  TextButton(onPressed: _retry, child: Text('Retry')),
                ],
              ),
            ),
        ],
      ),
    );
  }
}

Step-by-Step Explanation

1.

Create the API Service – Define a service that fetches pages with


          page

and


          limit

parameters.

2.

Set up state variables – Track


          _items

,


          _currentPage

,


          _isLoading

, and


          _hasMore

.

3.

Add ScrollController – Listen for scroll events to detect when the user reaches the bottom.

4.

Implement load more logic – When the user scrolls to the bottom (within 200px), fetch the next page.

5.

Show loading indicator – Display a progress indicator at the bottom while loading more items.

6.

Handle errors – Show error messages and provide a retry option.

Page-Based Pagination

Page-based pagination uses buttons to navigate between pages. This is common in web apps and some mobile apps.

        lib/page_based_screen.dart – Page-Based UI
       
import 'package:flutter/material.dart';

import 'pagination_service.dart';

class PageBasedScreen extends StatefulWidget {
  @override
  State<PageBasedScreen> createState() => _PageBasedScreenState();
}

class _PageBasedScreenState extends State<PageBasedScreen> {
  final PaginationService _service = PaginationService();

  int _currentPage = 1;

  int _totalPages = 0;
  List<dynamic> _items = [];

  bool _isLoading = false;

  bool _hasError = false;
  String? _errorMessage;

  @override
  void initState() {
    super.initState();
    _loadPage(1);
  }

  Future<void> _loadPage(int page) async {
    setState(() {
      _isLoading = true;
      _hasError = false;
      _errorMessage = null;
    });

    try {
      final result = await _service.fetchPage(page);

      final data = result['data'] as List<dynamic>;

      final hasMore = result['hasMore'] as bool;

      setState(() {
        _items = data;
        _currentPage = page;
        _isLoading = false;

        // In a real API, you'd get totalPages from the response

        _totalPages = hasMore ? page + 1 : page;
      });
    } catch (e) {
      setState(() {
        _isLoading = false;
        _hasError = true;
        _errorMessage = e.toString();
      });
    }
  }

  void _goToPage(int page) {
    if (page >= 1 && page <= _totalPages) {
      _loadPage(page);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Page-Based Pagination'), centerTitle: true),
      body: Column(
        children: [
          // Page navigation controls
          Container(
            padding: EdgeInsets.all(16),
            decoration: BoxDecoration(
              color: Colors.grey.shade50,
              border: Border(bottom: BorderSide(color: Colors.grey.shade200)),
            ),
            child: Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                IconButton(
                  icon: Icon(Icons.chevron_left),
                  onPressed: _currentPage > 1 && !_isLoading
                      ? () => _goToPage(_currentPage - 1)
                      : null,
                ),
                Text(
                  'Page $_currentPage',
                  style: TextStyle(fontWeight: FontWeight.bold),
                ),
                IconButton(
                  icon: Icon(Icons.chevron_right),
                  onPressed: _currentPage < _totalPages && !_isLoading
                      ? () => _goToPage(_currentPage + 1)
                      : null,
                ),
                SizedBox(width: 16),
                if (_totalPages > 0)
                  Text('of $_totalPages', style: TextStyle(color: Colors.grey)),
              ],
            ),
          ),

          // Content
          Expanded(
            child: _isLoading
                ? Center(child: CircularProgressIndicator())
                : _hasError
                ? Center(
                    child: Column(
                      mainAxisAlignment: MainAxisAlignment.center,
                      children: [
                        Icon(Icons.error, size: 64, color: Colors.red),
                        SizedBox(height: 16),
                        Text(_errorMessage ?? 'Failed to load data'),
                        SizedBox(height: 16),
                        ElevatedButton(
                          onPressed: () => _loadPage(_currentPage),
                          child: Text('Retry'),
                        ),
                      ],
                    ),
                  )
                : _items.isEmpty
                ? Center(child: Text('No items on this page'))
                : ListView.builder(
                    itemCount: _items.length,
                    itemBuilder: (context, index) {
                      final item = _items[index];

                      return Card(
                        margin: EdgeInsets.symmetric(
                          horizontal: 16,
                          vertical: 4,
                        ),
                        child: ListTile(
                          title: Text(item['title'] ?? 'No title'),
                          subtitle: Text(item['body'] ?? 'No body'),
                        ),
                      );
                    },
                  ),
          ),
        ],
      ),
    );
  }
}

Load More Button Pattern

The "Load More" button gives users explicit control over when to load more data. This is great for users with limited data plans or slow connections.

lib/load_more_screen.dart – Load More Button



         // Modify the infinite scroll screen to use a "Load More" button
        

         // instead of automatic scrolling.
        

         // Replace the ListView.builder itemCount with:
        
        itemCount: _items.length +
        
         1
        
        ,
        
         // +1 for the load more button
        

         // In the itemBuilder:
        

         if
        
        (index == _items.length) {
        
         return
        
        Container(
      padding: EdgeInsets.symmetric(vertical:
        
         16
        
        ),
      child: Center(
        child: _isLoading
            ? CircularProgressIndicator()
            : _hasMore
                ? ElevatedButton(
                    onPressed: _loadMore,
                    child: Text(
        
         'Load More'
        
        ),
                  )
                : Text(
        
         'No more items to load'
        
        ,
                    style: TextStyle(color: Colors.grey),
                  ),
      ),
    );
  }

Pagination Best Practices

✅ Do's

Always show a loading indicator when fetching more data
Handle and display errors with retry options
Use a reasonable page size (10-50 items per page)
Cache data locally to reduce API calls
Use ScrollController for infinite scroll detection
Prevent duplicate requests with loading state

❌ Don'ts

Don't fetch the same page multiple times
Don't ignore the loading state (avoid duplicate requests)
Don't make the page size too large (hurts performance)
Don't forget to handle the "no more items" state
Don't show loading indicators for empty pages

Common Mistakes

❌ Mistake 1: Not preventing duplicate requests

Without a loading state, users can trigger multiple requests by scrolling quickly or clicking "Load More" multiple times.

✅ Correct: Use a loading flag

Track _isLoading and check it before making any new request.

❌ Mistake 2: Not handling "no more items"

If you don't indicate that there are no more items, users will keep trying to load more.

✅ Correct: Show "No more items" message

When _hasMore is false, show a message instead of a loading indicator.

❌ Mistake 3: Hardcoding page size in multiple places

If the page size is used in multiple files, changing it becomes tedious and error-prone.

✅ Correct: Define page size as a constant

Use a static constant like static const int pageSize = 20; in your service class.

🎯 The Problem Pagination Solves

✅ Do's

❌ Don'ts

🎯 Key Takeaway