grighakobian/swift-pagination

Overview

Pagination provides an easy-to-use API for implementing infinite scrolling in your applications. It allows seamless integration of pagination functionality in any scrollable view — UITableView, UICollectionView, NSScrollView, or any other scrollable container.

With Pagination, you can effortlessly manage pagination in your app by automatically detecting when a user has scrolled close to the end of the current content and triggering the fetching of the next page. The framework supports both vertical and horizontal scrolling and is designed to work seamlessly with various UI components across iOS and macOS.

Features

• Easily integrates with UIScrollView, UITableView, UICollectionView, and NSScrollView.
• Works on both iOS and macOS.
• Supports both vertical and horizontal scroll directions.
• Provides customizable prefetching distance to control when the next batch of data is fetched.
• Objective-C Support: Fully compatible with Objective-C projects, making it easier to integrate into existing codebases.

Requirements

• iOS 13.0+ / macOS 11.0+
• Swift 6.0+

Getting Started

Implementing infinite scrolling is straightforward, especially with vertical scrolling. Set up the delegate to handle requests for new page prefetching

collectionView.pagination.delegate = self

Implement the delegate method to fetch data for the new page

func pagination(_ pagination: Pagination, prefetchNextPageWith context: PaginationContext) {
    context.update(state: .started)
    // Fetch the next page of data from your source
    fetchData(forPage: nextPage) { result in
        switch result {
        case .success(let data):
            // Append the new data and update UI.
            pagination.isEnabled = nextPage < data.totalPages
            context.update(state: .completed)
        case .failure:
            // Failed to fetch data
            context.update(state: .failed)
        }
    }
}

[!IMPORTANT] It is essential to call context.update(state: .started) when beginning a fetch and context.update(state: .completed) or context.update(state: .failed) once the data loading is complete to accurately update the pagination state.

To disable pagination, set the isEnabled property to false. This will stop pagination from monitoring the scrollable view

collectionView.pagination.isEnabled = false

For horizontal scrolling, configure pagination to handle horizontal scroll

collectionView.pagination.direction = .horizontal

To adjust the prefetching distance, set the leadingScreensForPrefetching property to your desired value. The default is 2 leading screens. Setting it to 0 will stop pagination from notifying you about new data prefetching

collectionView.pagination.leadingScreensForPrefetching = 3

Objective-C Integration

[!NOTE] Pagination is fully compatible with Objective-C projects. Simply import the module and use the provided APIs.

collectionView.pagination.isEnabled = YES;
collectionView.pagination.direction = PaginationDirectionVertical;
collectionView.pagination.leadingScreensForPrefetching = 3;
collectionView.pagination.delegate = self;

macOS Integration

The same API is available on macOS via NSScrollView:

scrollView.pagination.delegate = self
scrollView.pagination.direction = .horizontal

Examples

The Examples directory contains a sample project demonstrating Pagination across UIKit, AppKit, and Objective-C. Generate the Xcode project by running make examples from the repository root.

Installation

You can add pagination to an Xcode project by adding it as a package dependency.

https://github.com/grighakobian/swift-pagination

If you want to use Pagination in a SwiftPM project, it's as simple as adding it to a dependencies clause in your Package.swift:

dependencies: [
  .package(url: "https://github.com/grighakobian/swift-pagination", from: "1.1.1")
]

License

Pagination is available under the MIT license. See the LICENSE file for more info.

Package Metadata

Repository: grighakobian/swift-pagination

Default branch: main

README: README.md