# How to implement custom pagination · Chromia Docs (concept)

> This recipe demonstrates how to implement cursor-based pagination using custom pagination utilities in Rell and consume it from a client.

Source: https://docs.chromia.com/build/cookbook/query-creation/pagination/

# How to implement custom pagination

On this page

* [Prerequisites](#prerequisites)
* [Demo script](#demo-script)
* [Key Features](#key-features)
* [Architecture Overview](#architecture-overview)
* [Rell Module (Server-side)](#rell-module-server-side)
* [JavaScript Client](#javascript-client)
* [Custom Pagination Pattern](#custom-pagination-pattern)
* [Pagination Structures](#pagination-structures)
* [Cursor Management](#cursor-management)
* [Query Processing](#query-processing)
* [Client Usage Pattern](#client-usage-pattern)
* [Customization Benefits](#customization-benefits)
* [Use Cases](#use-cases)
* [Learn more](#learn-more)

This recipe demonstrates how to implement cursor-based pagination using custom pagination utilities in Rell and consume
it from a client. This approach provides full control over pagination logic and is ideal for projects that need
customized pagination behavior.

JS/TS client

## Prerequisites

* [Chromia CLI](https://docs.chromia.com/get-started/installation/)
* **Docker** (for local blockchain)
* **Node.js**
* [FT4 client](https://docs.chromia.com/build/ft4/intro/#client)
* [Postchain client](https://docs.chromia.com/build/clients/overview/)

## Demo script

* [Custom pagination demo](https://bitbucket.org/chromawallet/recipes/src/main/pagination/)

## Key Features

This recipe includes examples for:

* **Custom pagination utilities** - Custom-built pagination logic with full control over cursor behavior
* **Offset-based pagination** - Uses offset and limit for data retrieval with page tracking
* **Custom cursor encoding** - Base64-encoded cursors with page number tracking
* **Flexible page sizing** - Configurable page sizes with maximum limits

## Architecture Overview

The recipe includes both server and client components:

### Rell Module (Server-side)

* **Entity**: `user` with `name` field for demonstration
* **Query**: `get_users_paginated` with [`page_cursor`](https://docs.chromia.com/pages/ft4-rell/-f-t4-library/lib.ft4.utils/page_cursor/) and `data_size` parameters returning custom [`paged_result`](https://docs.chromia.com/pages/ft4-rell/-f-t4-library/lib.ft4.utils/paged_result/)
* **Operation**: `add_user` for seeding test data
* **Custom utilities**: `paginator.rell` module with pagination helper functions

### JavaScript Client

* **First page request** - Fetches initial data with [`page_cursor`](https://docs.chromia.com/pages/ft4-rell/-f-t4-library/lib.ft4.utils/page_cursor/) set to null
* **Subsequent pages** - Uses `next_cursor` from previous response
* **Page size control** - Uses `data_size` parameter for configurable page sizes

## Custom Pagination Pattern

The Rell implementation uses custom pagination utilities:

### Pagination Structures

* **page\_cursor**: Tracks current page position with `after_rowid` and `after_page`
* **pagination\_result**: Contains data and rowid for each result item
* **paged\_result**: Standard response format with `data` and `next_cursor`

### Cursor Management

* **encode\_cursor**: Converts cursor to base64-encoded string
* **decode\_cursor**: Parses cursor from client requests
* **Page tracking**: Maintains current page number for offset calculations

### Query Processing

* **fetch\_data\_size**: Fetches one extra item to determine if more pages exist
* **query\_offset\_for\_page\_size**: Calculates offset based on current page
* **make\_page**: Constructs response with appropriate next cursor

## Client Usage Pattern

The JavaScript client demonstrates the pagination flow:

* Initial request sets [`page_cursor`](https://docs.chromia.com/pages/ft4-rell/-f-t4-library/lib.ft4.utils/page_cursor/) to null and specifies `data_size`
* Each response includes `data` array and optional `next_cursor`
* Subsequent requests use the `next_cursor` to fetch following pages
* Pagination continues until `next_cursor` is null

## Customization Benefits

This custom approach offers several advantages:

* **Full control** - Complete control over pagination logic and cursor format
* **Flexible implementation** - Easy to modify pagination behavior for specific needs
* **Performance optimization** - Can implement custom indexing and query optimizations
* **Custom metadata** - Can include additional pagination metadata in responses

## Use Cases

This custom pagination approach is ideal for:

* **Custom sorting requirements** - Complex sorting that doesn't fit standard patterns
* **Specialized cursor logic** - Need for custom cursor encoding or metadata
* **Performance optimization** - Projects requiring specific query optimization strategies
* **Legacy integration** - Matching existing API pagination formats

## Learn more

* [Rell language](https://docs.chromia.com/rell/rell-intro/) — understanding how to create custom queries and utilities in Rell.
* [JavaScript/TypeScript client](https://docs.chromia.com/build/clients/postchain-clients/javascript-typescript/reference/) — covers client setup and
  usage.

[View this page on docs.chromia.com](https://docs.chromia.com/build/cookbook/query-creation/pagination/)Content mirrored from the live docs
