Pagy - A simple Flutter package for smooth pagination

🚀 Pagy - A Flutter Package for Pagination #

Pagy is a plug-and-play pagination solution for Flutter apps. It handles:

• API pagination (query params, body payloads, headers).
• Auto-cancel of duplicate API calls.
• Global styles (placeholders, shimmer, spacing).
• API interceptors (for auth tokens, retries, etc.).
• Logging and monitoring.
• Easy integration with Bloc, Riverpod, or direct controllers.
• Works with both light and dark themes automatically.
• Clean Architecture friendly – can be injected into repositories/services.

Usage #

Example: Paginating Property Data #

Here’s an example of how you can use Pagy in your project to paginate through property data from an API:

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

import 'views/nav_screen.dart';

void main() {
  PagyConfig().initialize(
    baseUrl: "Your API Base URL",
    pageKey: 'page',
    limitKey: 'limit',
  );

  runApp(const PagyExampleApp());
}

📄 Basic ListView Example #

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

import '../models/property_model.dart';
import '../widgets/property_card_widget.dart';

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

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  late PagyController<PropertyModel> pagyController;

  @override
  void initState() {
    super.initState();
    pagyController = PagyController(
      endPoint: "properties",
      requestType: PagyApiRequestType.post,
      fromMap: PropertyModel.fromJson,
      limit: 4,
      responseMapper: (response) {
        return PagyResponseParser(
          list: response['data'],
          totalPages: response['pagination']['totalPages'],
        );
      },
      paginationMode: PaginationPayloadMode.queryParams,
    );

    pagyController.loadData();
  }

  @override
  Widget build(BuildContext context) {
    return PagyListView<PropertyModel>(
      itemSpacing: 10,
      padding: const EdgeInsets.symmetric(horizontal: 14),
      // separatorBuilder: (context, index) => const Divider(),
      controller: pagyController,
      placeholderItemCount: 10,
      shimmerEffect: true,
      placeholderItemModel: PropertyModel(),
      itemBuilder: (context, item) {
        return PropertyCardWidget(data: item);
      },
    );
  }
}