FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

The ColdBox Paginator

v2.3.0 Public

Welcome to the Pagination Module

This module builds the pagination struct for API responses and custom data tables.


Apache License, Version 2.0.


  • Adobe ColdFusion 2016+
  • Lucee 4.5 or later


Just drop into your modules folder or use the box cli to install

box install cbpaginator


First you will need to inject the paginator into your service/handler:

property name="cbpaginator" inject="[email protected]";

This module provides two functions to build your pagination struct:


public struct function generate(
    numeric totalRecords = 0,
    numeric page = 1,
    numeric maxRows = 25

Returns the pagination struct according to the total records.

If page and maxRows parameters are not passed in, it will use the default values.

The response will look like the following:

    "totalPages": 0,
    "maxRows": 25,
    "offset": 0,
    "page": 1,
    "totalRecords": 0


public struct function generateWithResults(
    numeric totalRecords = 0,
    array results = [],
    numeric page = 1,
    numeric maxRows = settings.defaults.maxRows,
    boolean asResultsMap = false,
    string keyName = "id",
    string resultsKeyName = "results"

This function returns the same pagination struct as the above along with the results

You can convert your results to be a resultsMap by setting asResultsMap to true

In addition you can set a name for your results key by passing in the resultsKeyName value as a parameter. By default this key is called results

    "pagination": {
        "totalPages": 0,
        "maxRows": 25,
        "offset": 0,
        "page": 1,
        "totalRecords": 0
    "results": [],
    // optional
    "resultsMap": {}

Helper Method


Since we have to calculate the offset before we filter our data we can use the getPageOffset() function to calculate that number for us

	public function getPageOffset( 
        page = 1,
        maxRows = 25 

This function receives two arguments. The page number and the maxRows to retrieve. If no params are passed in, the defaults will be used.

Dependencies (0)

Dev Dependencies (1)


$ box install cbpaginator

No collaborators yet.
  • Sep 25 2020 08:59 PM
  • Sep 28 2020 10:13 PM
  • 27
  • 0
  • 241