/pagination

name: pagination
description: Generates pagination infrastructure with offset or cursor-based patterns, infinite scroll, and search support. Use when user wants to add paginated lists, infinite scrolling, or load-more functionality.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Pagination Generator

Generate production pagination infrastructure supporting offset-based and cursor-based APIs, with infinite scroll SwiftUI views, state machine management, and optional search integration.

When This Skill Activates

Use this skill when the user:

• Asks to "add pagination" or "paginate a list"
• Wants "infinite scroll" or "load more" functionality
• Mentions "cursor-based pagination" or "offset pagination"
• Asks about "paginated API" or "loading pages of data"
• Wants "search with pagination"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Check deployment target (iOS 17+ / macOS 14+ for @Observable)
• [ ] Search for existing pagination implementations
• [ ] Identify source file locations

2. Networking Layer Detection

Search for existing networking code:

Glob: **/*API*.swift, **/*Client*.swift, **/*Endpoint*.swift
Grep: "APIClient" or "APIEndpoint"

If `networking-layer` generator was used, detect the `APIEndpoint` protocol and generate data sources that conform to it.

3. Conflict Detection

Search for existing pagination:

Glob: **/*Pagina*.swift, **/*LoadMore*.swift
Grep: "PaginationState" or "loadNextPage" or "hasMorePages"

If found, ask user whether to replace or extend.

Configuration Questions

Ask user via AskUserQuestion:

1. **Pagination style?**

• Offset-based (page number + page size) — most common for REST APIs
• Cursor-based (opaque cursor token) — better for real-time data, social feeds

2. **Loading trigger?**

• Infinite scroll (auto-load when near bottom) — recommended
• Manual "Load More" button
• Both (infinite scroll with manual fallback on error)

3. **Additional features?** (multi-select)

• Search with pagination (debounced, resets on query change)
• Pull-to-refresh
• Empty/error/loading state views

4. **Data source pattern?**

• Generic (works with any Codable model)
• Protocol-based (define per-endpoint data sources)

Generation Process

Step 1: Read Templates

Read `pagination-patterns.md` for architecture guidance. Read `templates.md` for production Swift code.

Step 2: Create Core Files

Generate these files: 1. `PaginatedResponse.swift` — Generic response models for offset and cursor 2. `PaginationState.swift` — State machine (idle, loading, loaded, error, exhausted) 3. `PaginatedDataSource.swift` — Protocol endpoints conform to 4. `PaginationManager.swift` — @Observable manager with state transitions

Step 3: Create Optional Files

Based on configuration:

• `SearchablePaginationManager.swift` — If search selected
• `Views/PaginatedList.swift` — Infinite scroll SwiftUI wrapper
• `Views/LoadMoreButton.swift` — Manual load-more button
• `Views/PaginationStateView.swift` — Empty/loading/error state views

Step 4: Determine File Location

Check project structure:

• If `Sources/` exists → `Sources/Pagination/`
• If `App/` exists → `App/Pagination/`
• Otherwise → `Pagination/`

Output Format

After generation, provide:

Files Created

Pagination/
├── PaginatedResponse.swift           # Generic response models
├── PaginationState.swift             # State machine enum
├── PaginatedDataSource.swift         # Data source protocol
├── PaginationManager.swift           # @Observable manager
├── SearchablePaginationManager.swift # Optional: search + pagination
└── Views/
    ├── PaginatedList.swift           # Infinite scroll wrapper
    ├── LoadMoreButton.swift          # Manual load-more
    └── PaginationStateView.swift     # Empty/loading/error states

Integration Steps

**Define a data source:**

struct UsersDataSource: PaginatedDataSource {
    typealias Item = User

    let apiClient: APIClient

    func fetch(page: PageRequest) async throws -> PaginatedResponse<User> {
        try await apiClient.request(UsersEndpoint(page: page.page, size: page.size))
    }
}

**Use PaginationManager in a view model:**

@Observable
final class UsersViewModel {
    let pagination: PaginationManager<UsersDataSource>

    init(apiClient: APIClient) {
        pagination = PaginationManager(
            dataSource: UsersDataSource(apiClient: apiClient)
        )
    }
}

**With SwiftUI (infinite scroll):**

struct UsersListView: View {
    @State private var viewModel = UsersViewModel()

    var body: some View {
        PaginatedList(manager: viewModel.pagination) { user in
            UserRow(user: user)
        }
        .task {
            await viewModel.pagination.loadFirstPage()
        }
    }
}

**With search:**

struct SearchableUsersView: View {
    @State private var searchManager = SearchablePaginationManager(
        dataSource: UsersDataSource()
    )

    var body: some View {
        PaginatedList(manager: searchManager.pagination) { user in
            UserRow(user: user)
        }
        .searchable(text: $searchManager.query)
    }
}

Testing

@Test
func loadFirstPagePopulatesItems() async throws {
    let mockSource = MockDataSource(items: User.mockList(count: 20))
    let manager = PaginationManager(dataSource: mockSource, pageSize: 10)

    await manager.loadFirstPage()

    #expect(manager.items.count == 10)
    #expect(manager.state == .loaded)
    #expect(manager.hasMore == true)
}

@Test
func loadAllPagesReachesExhausted() async throws {
    let mockSource = MockDataSource(items: User.mockList(count: 15))
    let manager = PaginationManager(dataSource: mockSource, pageSize: 10)

    await manager.loadFirstPage()
    await manager.loadN