flutter_pagination_widget #

A lightweight, responsive, overflow-proof, and fully customizable pagination widget for Flutter. Easily integrate modern pagination controls into your mobile, web, or desktop applications without relying on external dependencies.

✨ Features #

• 📱 Cross-Platform: Mobile, Web, and Desktop ready.
• 🧮 Smart Pagination Model: Calculate page ranges (from, to, lastPage) automatically via PaginationModel.calculate().
• 🔢 Rows Per Page Selector: Optional dropdown selector (e.g. 10, 20, 50, 100) with onPageSizeChanged callback.
• 🚀 Direct Jump to Page: Sleek inline page input field with automatic out-of-bounds page clamping and keyboard dismissal.
• ⏭️ First & Last Page Navigation: Quick navigation controls (firstPageChild, lastPageChild).
• 📐 Adaptive Layouts: Four layout modes (PaginationLayoutMode.auto, row, wrap, column) to prevent UI overflows on narrow screens.
• 🎨 Rich Customization: Custom colors, borders, padding, font styles, and custom item builders (pageButtonBuilder, infoTextBuilder).
• 📦 Zero External Dependencies: 100% Dart & Flutter.

💻 Installation #

Add flutter_pagination_widget to your pubspec.yaml:

dependencies:
  flutter_pagination_widget: ^0.1.0

Then run:

flutter pub get

🚀 Usage #

1. Simple Usage with PaginationModel.calculate #

Use PaginationModel.calculate to automatically compute entry bounds and total pages based on your total item count and page size:

import 'package:flutter/material.dart';
import 'package:flutter_pagination_widget/flutter_pagination_widget.dart';

class SimplePaginationExample extends StatefulWidget {
  const SimplePaginationExample({super.key});

  @override
  State<SimplePaginationExample> createState() => _SimplePaginationExampleState();
}

class _SimplePaginationExampleState extends State<SimplePaginationExample> {
  int currentPage = 1;
  int pageSize = 10;
  final int totalItems = 125;

  @override
  Widget build(BuildContext context) {
    // Automatically calculates 'from', 'to', and 'lastPage'
    final meta = PaginationModel.calculate(
      total: totalItems,
      currentPage: currentPage,
      pageSize: pageSize,
    );

    return Scaffold(
      body: Center(
        child: PaginationWidget(
          meta: meta,
          onPageChanged: (page) => setState(() => currentPage = page),
          onPageSizeChanged: (newSize) {
            setState(() {
              pageSize = newSize;
              currentPage = 1; // Reset to page 1 when page size changes
            });
          },
          showFirstLastButtons: true,
          showPageSizeSelector: true,
          showJumpToPage: true,
          pageSizeOptions: const [10, 20, 50, 100],
          primaryColor: Colors.teal,
        ),
      ),
    );
  }
}

2. Advanced Customization & Builders #

PaginationWidget(
  meta: meta,
  onPageChanged: (page) => setState(() => currentPage = page),
  
  // Feature Toggles
  showInfoText: true,
  showFirstLastButtons: true,
  showPageSizeSelector: true,
  showJumpToPage: true,

  // Layout Mode & Page Range
  layoutMode: PaginationLayoutMode.auto,
  visiblePagesCount: 2,

  // Custom Colors & Styles
  primaryColor: Colors.deepPurple,
  activeBackgroundColor: Colors.deepPurple,
  activeTextColor: Colors.white,
  inactiveBackgroundColor: Colors.grey.shade100,
  disabledBackgroundColor: Colors.grey.shade100,
  disabledTextColor: Colors.grey.shade400,
  borderColor: Colors.deepPurple.shade100,
  borderRadius: BorderRadius.circular(10),
  buttonPadding: 10.0,

  // Custom Text Formatters
  infoTextBuilder: (from, to, total) => 'Displaying $from - $to of $total items',
  pageSizeLabel: 'Items per page:',
  jumpToPageLabel: 'Go to:',

  // Custom Item Builder
  pageButtonBuilder: (context, page, isSelected, onTap) {
    return GestureDetector(
      onTap: onTap,
      child: Container(
        margin: const EdgeInsets.symmetric(horizontal: 4),
        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
        decoration: BoxDecoration(
          color: isSelected ? Colors.deepPurple : Colors.transparent,
          borderRadius: BorderRadius.circular(20),
          border: Border.all(color: Colors.deepPurple),
        ),
        child: Text(
          '$page',
          style: TextStyle(
            color: isSelected ? Colors.white : Colors.deepPurple,
            fontWeight: FontWeight.bold,
          ),
        ),
      ),
    );
  },
)

🛠️ API Reference #

PaginationWidget Properties #

PaginationModel Properties #

📄 License #

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