The following post assumes a basic understanding of server-side programming.

Pagination: What is it? Why do I need it?

There is a hard limit on the number of “records” a “server” can deliver:

def index
    @users = User.all # all 100,000,000 users
                      # haha good luck!
                      # your server will explode!
end

A pagination library helps solve this problem, allowing you to break-up records (or any “collection”) into small digestable chunks - i.e. “pages” that a server can comfortably deliver. People can then thumb through records as if they were pages in a book, split up, by say, 25 users per page.

Pagination libraries like: Pagy, Kaminari and will_paginate help you do that, writing barely a lick of code.

My preference is to use pagy, for the following reasons:

• (i) it has a focus on performance, and
• (ii) it’s easy to configure, and
• (iii) for 99% of use cases, it solves my problems with only a few lines of code.

That’s not to disparage the other solutions: many have used Kaminari and will_paginate with success. They’ve been created and maintained with a lot of patience and <3, though I cannot comment on them, because I’m not familiar with them.

Show Your Users What They Want to See

Keep in mind that dumping 1000s of records onto users, though they are paginated, might not be a great experience for them. Human beings are not machines. They need to make sense of what is presented to them. Consider presenting the minimum to them, without exhausting their minds, allowing them to easily sort records and to quickly find what they are looking for. As an example, consider a Google search result: millions of applicable records are delivered. They are paginated. Do we bother to look at page 15, or page 40? Of the first page, how many records do we actually see? How should the results be presented? How should you help users further find what they are looking for? The better you answer these questions, the better your application will be for your users.

Basic Use Cases - What do I get if I use pagy?

Most will want either HTML or json returned:

1. HTML returned: You can return paginated html links styled acording to your framework of choice. The image below is a bootstrap example, but many other frameworks are available: bulma, semantic, tailwind etc.

2. JSON returned: If you are developing a back-end API with a front-end framework like React / Vue you can choose between the following to help display or handle pagination:

• (i) using a client-side javascript navigation component, or
• (ii) you can roll your own using the meta-data extra (which allows you to easily write your own code to go to which ever page you want etc.). This is an option if your client is non-human.
• (iii) Finally, if you do not want pagination logic to exist in response bodies, you can choose to put them in response headers using the headers extra. This is also an option for non-human clients.

Advanced Use Cases in Pagy

Pagy is eminently customisable.

Consider looking through pagy’s extras for more information about special customisations that can be applied, with very little code.

And if those don’t suffice, and you want still further customization, you can override some of pagy’s internal methods, or you can override methods only in specific circumstances.