This guide is to help you understand the concept of pagination and how to implement it in react, the concepts in this tutorial can be applied to any javascript project.
๐คจ What is Pagination?
Pagination is the process of separating print or digital content into discrete pages. For print documents and some online content, pagination also refers to the automated process of adding consecutive numbers to identify the sequential order of pages.
Concept behind it? ๐ป
Let's say you have a total of 6 items on a page, and you want to only display 3 items at a time (per page). This means we are going to have a total of 2 pages, and if we want to display 2 items per page this means a total of?? you guessed it! 3 pages.
This formular is rather simple:
totalPages = totalContent / contentPerPage
Implementing it in Javascript (.slice()) ๐ช
Calculating the content per page is rather easy, but how do we display certain content based on what page we are on? We simply need to understand the relationship between the page and the index
of our content. Let first understand the .slice()
Array method.
The slice() method returns a shallow copy of a portion of an array into a new array object selected from start to end (end not included) where start and end represent the index of items in that array. The original array will not be modified.
For example, let's say we have an array called scouts
and we want to select only a portion of this array based on the array's index.
const scouts = ["levi", "hange", "erwin", "petra", "oruo", "miche"]
scouts.slice(2, 5)
// output: [ 'erwin', 'petra', 'oruo' ]
scouts.slice(1, 3)
// output: [ 'hange', 'erwin' ]
We all know javascript follows a zero-based index, so the first parameter is the index from which we want to start the slice from and the second parameter is the index right after where we want the slice to end. e.g if we want 2 to 4 we use .slice(2, 5)
as seen in the first example.
Mapping page number to index
All we need to do is know what the startIndex
and lastIndex
should be based on the page number. this relationship is quite simple.
As you can tell from the diagram above the last index is simply the current page multiplied by the given content by page, while the first index is the content by page subtracted from the last index.
// assuming we are on page one
const page = 1;
const contentPerPage = 3
const lastIndex = page * contentPerPage // 3
const firstIndex = lastIndex - contentPerPage // 0
scouts.slice(firstIndex, lastIndex)
// scouts.slice(0, 3) => [ 'levi', 'hange', 'erwin' ]
// page 2
// scouts.slice(3, 6) => [ 'petra', 'oruo', 'miche' ]
Wow!, that was easy ๐ณ.
Custom usePagination
hook ๐ฃ
Now that we've learned the concept behind it, let's implement this in react and create our custom hook to help us automate this process.
This hook takes in an object that takes in the properties contentPerPage
which is how many items should be displayed at a time and count
which is the total number of items given (Array length). It also returns an object with the following properties.
-
page
- current page we are on -
totalPages
- total number of pages generated -
firstContentIndex
- first index for the.slice()
method -
lastContentIndex
- last index for the.slice()
method -
nextPage
- function to navigate one page foward -
prevPage
- function to navigate one page backward -
setPage
- function to go to a certain page
The type definitions are as follows:
interface UsePaginationProps {
contentPerPage: number,
count: number,
}
interface UsePaginationReturn {
page: number;
totalPages: number;
firstContentIndex: number;
lastContentIndex: number;
nextPage: () => void;
prevPage: () => void;
setPage: (page: number) => void;
}
type UsePagination = (UsePaginationProps) => (UsePaginationReturn);
In your React project create a folder called hooks
and create a file called usePagination
, this is where our custom hook will reside.
Type the following within it
import { useState } from "react";
const usePagination: UsePagination = ({ contentPerPage, count }) => {
const [page, setPage] = useState(1);
// number of pages in total (total items / content on each page)
const pageCount = Math.ceil(count / contentPerPage);
// index of last item of current page
const lastContentIndex = page * contentPerPage;
// index of first item of current page
const firstContentIndex = lastContentIndex - contentPerPage;
// change page based on direction either front or back
const changePage = (direction: boolean) => {
setPage((state) => {
// move forward
if (direction) {
// if page is the last page, do nothing
if (state === pageCount) {
return state;
}
return state + 1;
// go back
} else {
// if page is the first page, do nothing
if (state === 1) {
return state;
}
return state - 1;
}
});
};
const setPageSAFE = (num: number) => {
// if number is greater than number of pages, set to last page
if (num > pageCount) {
setPage(pageCount);
// if number is less than 1, set page to first page
} else if (num < 1) {
setPage(1);
} else {
setPage(num);
}
};
return {
totalPages: pageCount,
nextPage: () => changePage(true),
prevPage: () => changePage(false),
setPage: setPageSAFE,
firstContentIndex,
lastContentIndex,
page,
};
};
export default usePagination;
We are managing the current page value with useState
, also notice that pageCount
is also equal to the value of the last page. I've made the code above as explanatory as I can.
Implementation โ๐พ
We simply import the hook then input the needed properties.
...
const {
firstContentIndex,
lastContentIndex,
nextPage,
prevPage,
page,
setPage,
totalPages,
} = usePagination({
contentPerPage: 3,
count: people.length,
});
...
Then we simply slice our data with the firstContentIndex
and lastContentIndex
.
...
<div className="items">
{people
.slice(firstContentIndex, lastContentIndex)
.map((el: any) => (
<div className="item" key={el.uid}></div>
))}
</div>
...
Below is a simple functionality to help us generate our buttons, then we add their corresponding onClick
handlers.
<div className="pagination">
<p className="text">
{page}/{totalPages}
</p>
<button onClick={prevPage} className="page">
←
</button>
{/* @ts-ignore */}
{[...Array(totalPages).keys()].map((el) => (
<button
onClick={() => setPage(el + 1)}
key={el}
className={`page ${page === el + 1 ? "active" : ""}`}
>
{el + 1}
</button>
))}
<button onClick={nextPage} className="page">
→
</button>
</div>
We are done! As you can see below our usePagination
hook works as planned.
Thank you for reading ๐๐พ, If you have any questions, additions, or subtractions please comment below.
The full source code is linked below ๐๐
Top comments (32)
Hi Everyone, I've noticed most of you guys are requesting for features like the ability for the repo to handle more than 1000 pages, the
usePagination()
hook can handle โ number of pages. But you guys are should understand that this blog post is simply to show theusePagination()
hook and has nothing to do with the pagination buttons or styling. Some of you are requesting that I should add the UI functionality of...
in the middle of the pagination buttons for pages that are as large as a 100 pages. This require for theusePagination()
hook to also return a component that contains the pagination buttons.If you'd like me to implement this, please get the github repo to 50 stars and i'll convert this into a full library that tackles these issues and more.
You are also free to collaborate on this repo so we can build it as a library together ๐
Thank you ๐๐๐๐
Here's a fully functional
usePagination
hook, with a demo of rendering buttons and an ellipsis: mui.com/components/pagination/#use...Thatโs great, but youโll need install the โ@muiโ library to use it
Well, sure, but that's a single command (
yarn add
ornpm install
). And since all you import is the hook, that's all that will be included in your bundle.I'll try that, but I'll still challenge myself and create a npm package, it will be my first open source project
Of course! And perhaps youโll find a more elegant implementation. Itโs a tricky problem to solve! Good luck! ๐
Do you have a working demo? Does't it work with 1000 pages?
The number of pages fully depend on the
contentPerPage
, the API route I used in the code only returns an array of 20 items so the maximum possible number of pages is either 1 or 20, with 3contentPerPage
it generated 7 pagesHere is a working demo => use-pagination.vercel.app/
So it's not fully functional pagination. Just a simple demo.
Here is example how pagination should work (the code is in PHP but it's algorithm that can be rewritten in any language).
gist.github.com/bramus/5d8f2e0269e...
Also note that prev should be disabled when on first page.
It's functional, I was referring to Typescript you were talking about types. There are many ways to implement pagination, this is just my way, and this will work for any language
I don't quite understand what you write this above comment. I just mean that this is not fully implemented pagination, because it's missing fundamental features. So it can't be used in any real projects. You need to implement the thing yourself if you want to have something that is a full pagination. Also this will not work with any language because it's like half of the implementation.
Sorry I thought I replied to another comment, could you list out these features, so I improve this React hook
You are also free to make contributions to the repo
Added two issues. I may contribute if the issue is not fixed when I will need pagination since I will need something like this in the near future for my application.
๐๐ฝ
Thanks for this article @damiisdandy โ the illustrations are very helpful and I appreciate the time you spent to share this with the community! Very happy you used buttons too :)
I coded this up for my AgnosticUI library and found my SRP cohesion was best when I made my
usePagination.ts
hook only concerned with generating the paging links. Then myPagination.tsx
provided the React view and the consumer could simply DI inject the generated pages into the component. The consumer actually keeps track ofconst [currentPage, setCurrentPage] = useState(1)
and listens for aonPageChanged
callback resulting in updating the current page. That in turn triggers theuseEffect
that just asks for the pages to be regenerated with the new current page. It all seems to work quite nicely!Also, I looked at many many examples on the web and found one somewhere that utilizes currying and utilized that approach as it's extremely efficient and readable:
My API allows you to use 1 or 2 for padding (I've also seen this called one of: "gap" or "offset" or "siblingCount"). Looking at Ant Design and Zen Garden, they both used padding of 1 on both sides but I think 2 is nice to have as an option. The curry approach above is so crystal clear it almost feels like cheating, but, it's also very efficient for large data sets. Thoughts?
I'm actually work-in-progress on this so I don't have a link with live example but I've completed (I think) my React implementation here: pagination component and pagination hook. It gives tabbing for free since it uses buttons (quite similar to how you've done I think; yay for using semantic elements!)
I wonder if this might be an interesting alternative approach for these folks asking about > 1k pages as the curry approach isn't affected by size nor does it require a massive loop. Wish I could take credit but I saw it in a gist "somewhere" and adapted it to my needs. What a challenging programming task to write a good pagination! I'd fail this in a timed interview for sure lol
Thanks so much, and your idea is solid!
Hi @damiisdandy just a small doubt,
In changePage function how does state variable work ?
And what's the difference between props data type with and without it ?
say (x : number) || (x)
Btw great code
the
changePage
function simply takes in a boolean of eithertrue
orfalse
, iftrue
the page state is incremented, and iffalse
the page state is decremented.there is no functional difference between adding a data type, this is just used so you can't predict the type of value used in the function later and to aid IntelliSense in your IDE. if a data type is not provided typescript will read it as a type of
any
which is okay.Also with the
useState()
hooksetPage()
can either take in a number or a function that returns a number, which is what I used.usePaginationReturn
is an interface for an object not a function.The above
type
is the correct implementation.usePaginationReturn
is an interface for an object, returning from a function, so thisis equivalent to this
Just -1 type
Nice
Thanks, glad you liked it
Awesome
Thanks ๐๐ฝ
Very clear , thanks
You are welcome โค๏ธ
Thank you โก
it doesn't work when you have many pages like more than 100
Can you share a piece of the code you wrote, 100 pages depends on the content per page. It should work for any number.