README.md

next-server-pagination

Add pagination to your next.js app with one function. The library works with React Server Components, so you can limit how much data you read from database and send to client. Page navigation is fully customizable.

Installation

npm install next-server-pagination

Usage

Just wrap your server component with withPagination and pass a function that returns number (or a Promise<number>) of elements as a second argument. The third, optional argument is a settings object.

Then you can access page property inside your component and use it to limit data you read from database. Page property is of type PageData.

IMPORTANT! This library uses searchParams to store page number and other data. If you use withPagination outside of page.tsx, you need to pass searchParams manually as a prop. (see non page component example)

To add page navigation, create a client component and call usePagination hook. It returns functions like next, previous (see UsePagination type)

Example

In this example data is a simple array, but you can for example use prisma with skip and take to limit data you read from database.

page.tsx

import { withPagination, PageData } from 'next-server-pagination';
import { data } from './data';
import PageSwitcher from './pageSwitcher';

async function getDataLength() {
    return data.length;
}

async function getData(start: number, end: number) {
    return data.slice(start, end + 1);
}

async function Page({ page }: { page: PageData }) {
    // access page data ^ in your component
    const data = await getData(page.firstElement, page.lastElement);

    return (
        <>
            <div className="grid grid-cols-4 gap-4 mx-auto max-w-4xl p-2 my-4">
                {data.map((element, index) => (
                    <div
                        className="rounded-lg border border-slate-400 p-4 text-center"
                        key={index}
                    >
                        {element}
                    </div>
                ))}
            </div>
            <PageSwitcher />
        </>
    );
}

export default withPagination(Page, getDataLength);
//    just add ^^^^

pageSwitcher.tsx

'use client';

import { usePagination } from 'next-server-pagination';

export default function PageSwitcher() {
    const page = usePagination();

    return (
        <div className="flex items-center justify-center">
            <button
                onClick={page.previous}
                disabled={page.isFirst}
                className="rounded-md py-1 px-2 border border-black"
            >
                &lt;
            </button>
            <p className="mx-4">
                {page.current} / {page.total}
            </p>
            <button
                onClick={page.next}
                disabled={page.isLast}
                className="rounded-md py-1 px-2 border border-black"
            >
                &gt;
            </button>
        </div>
    );
}

Types

If you want to add add type to your component's props, you can either

• type page props as PageData

import { PageData } from 'next-server-pagination';

function Page({ page }: { page: PageData }) {
    ...
}
export default withPagination(Page, getDataLength);

• whole props object as WithPaginationProps (then you can also use searchParams)

import { WithPaginationProps } from 'next-server-pagination';

function Page({ page }: WithPaginationProps) {
    ...
}
export default withPagination(Page, getDataLength);

• or declare a component inside withPagination and props will be infered automatically

import { withPagination } from 'next-server-pagination';

export default withPagination(
    function Page({ page }) {
        ...
    },
    getDataLength
);

PageData

Property	Type	Description
current	number	Index of the page that user is currently on. It is an integer between 1 and total.
total	number	Total number of pages.
size	number	Number of elements per page.
firstElement	number	Index of the first element on the page.
lastElement	number	Index of the last element on the page.

UsePagination

Includes all properties from PageData and:

Property	Type	Description
isFirst	boolean	Whether the user is on the first page.
isLast	boolean	Whether the user is on the last page.
next	() => void	Switches to the next page.
previous	() => void	Switches to the previous page.
setPage	(page: number) => void	Switches to the specified page.
setSize	(size: number) => void	Sets the number of elements per page.

PaginationSettings

Property	Type	Default	Description
defaultSize	number	20	Default number of elements per page. It is used if size is not provided in search params