Server-Side Pagination Made Easy in Payload CMS

Long before JavaScript was really a popular web framework technology or even before it could even make a fetch to the server using XHR, all web page pagination was rendered from the server-side. With the arrival of React Server Components (RSC), we can once again take advantage of server-side pagination using modern frameworks like Next.js and Payload CMS?
In this article I'll show you how to use Next.js and Payload CMS to easily provide server-side pagination. Payload provides all of the API endpoints needed to make the job easy.
In this article, I will cover:
- What is the difference between server and client pagination.
- Server-side pagination using React Server Components (RSC).
- Payload API support for pagination.
- How to use Next.js to do the server-side rendering.
So, let's take a step back in time and see how pagination was done in the early days but using a modern approach with React.
What is Server-Side Pagination?
Similar to client-side pagination, a fetch is called to load the next page of data. The difference being that server-side pagination will make the fetch on the server before it ever reaches the browser.
In addition, server-side pagaination does not have access to the following features:
- No React hooks, including the Next.js client hooks params, searchParams, useRouter, etc
- No DOM actions or events.
- No access to Browser features.
Typically a client pagination component will make use of hooks to store state, fetch page data or redirect for example using the useRouter in Next.js.
The server-side pagination approach will make use of query string params, or even path params, to maintain the state of the pagination, for example:
1http://<host>/orders?page=123or using path params45http://<host>/orders/page/1
So a server pagination component can easily build static links for subsequent calls to load a specific page of data based on the given query param.
Building a Server Paginator
To build a server-side paginaton component, we'll need the following pieces of code.
- A Payload Collection endpoint to query page data from.
- A Next.js server page (RSC).
- A Pagination component (RSC).
Also, in order to paginate data, we'll need to know two values from the API:
- Total pages or Total docs (records)
- Items per page.
For example, if we have 85 total docs
1const totalDocs = 852const pageSize = 10 // items to show per page3const totalPages = Math.ceil(totalDocs/pageSize) // 9 pages
Since we're rounding up, the last page will be a partial page with only the remaining 5 items.
One of the great features of Payload CMS is that it takes the hard work out of pagination by providing all the data points we'll need.
So let's start on the server endpoint before we create the actual pagination component.
A Simple Payload Collection
For this example I'll define a simple Orders Collections to hold some data and seed it with some random data.
1import type { CollectionConfig } from 'payload'23export const Orders: CollectionConfig = {4 slug: 'orders',5 admin: {6 useAsTitle: 'orderNumber',7 defaultColumns: ['orderNumber', 'item', 'total'],8 },9 access: {10 read: () => true,11 update: () => true,12 create: () => true,13 delete: () => true,14 },15 fields: [16 {17 name: 'orderNumber',18 label: 'Order Number',19 type: 'number',20 },21 {22 name: 'item',23 label: 'Item name',24 type: 'text',25 },26 {27 name: 'total',28 label: 'Total',29 type: 'number',30 min: 0,31 },32 ],33}



