@ajna/pagination

Table of Contents

• Version
• Installation
• Demo with all options applied
• Components
  • Pagination
  • PaginationContainer
  • PaginationPageGroup
  • PaginationPrevious
  • PaginationNext
  • PaginationPage
  • PaginationSeparator
• Hooks
  • usePagination
• Usage
  • Minimal
  • Styling
  • Disabling
  • Page size
  • Limits
  • Separator
  • Offset
  • Total
  • Full usage example

Version

Installation

npm

1npm i @ajna/pagination

Yarn

1yarn add @ajna/pagination

Demo with all options applied

Check it out in this Sandbox

Components

Pagination

Prop	Description	Type	Default	Required
pagesCount	The total number of pages	number		yes
currentPage	The page which is currently being selected	number		yes
onPageChange	On change handler which returns the last selected page	(currentPage: number) => void		yes
isDisabled	Denotates if all items on the pagination are disabled or not	boolean	false	no

PaginationContainer

It's a Flex component, so any FlexProps are accepted

PaginationPageGroup

It's a Stack component, so any StackProps are accepted

PaginationPrevious

It's a Button component, so any ButtonProps are accepted

PaginationNext

It's a Button component, so any ButtonProps are accepted

PaginationPage

It's a Button component, so any ButtonProps are accepted

PaginationSeparator

It's a Button component, so any ButtonProps are accepted

Hooks

usePagination

Options

Prop	Description	Type	Default	Required
initialState	Initial states for pagination values	InitialState		yes
total	The total amount of items from the endpoint you are consuming	number	undefined	no
limits	The limits cut the amount of pages to show	Limits	undefined	no
pagesCount	If the amount of pages is manually set, it will take precedence	number	undefined	no

Returned values

Prop	Description	Type	Default
offset	Offset value generated	number	0
pages	The array of pages to render	number[]	[]
pagesCount	The total amount of pages	number	0
currentPage	The page which is currently being selected	number
pageSize	The amount of items per page	number	undefined
isDisabled	Denotates if all items on the pagination are disabled or not	boolean	false
setPageSize	A setter for the isDisabled value	Dispatch<SetStateAction>
setIsDisabled	A setter for the isDisabled value	Dispatch<SetStateAction>
setCurrentPage	A setter for the currentPage value	Dispatch<SetStateAction>

Usage

Minimal

This is the bare minimum set up you need to get it up and working

1import React, { FC, ChangeEvent, useEffect, useState } from "react";
2import { ChakraProvider } from "@chakra-ui/react";
3import {
4  Pagination,
5  usePagination,
6  PaginationNext,
7  PaginationPage,
8  PaginationPrevious,
9  PaginationContainer,
10  PaginationPageGroup,
11} from "@ajna/pagination";
12
13const Minimal: FC = () => {
14  const {
15    currentPage,
16    setCurrentPage,
17    pagesCount,
18    pages
19  } = usePagination({
20    pagesCount: 12,
21    initialState: { currentPage: 1 },
22  });
23
24  return (
25    <ChakraProvider>
26      <Pagination
27        pagesCount={pagesCount}
28        currentPage={currentPage}
29        onPageChange={setCurrentPage}
30      >
31        <PaginationContainer>
32          <PaginationPrevious>Previous</PaginationPrevious>
33          <PaginationPageGroup>
34            {pages.map((page: number) => (
35              <PaginationPage 
36                key={`pagination_page_${page}`} 
37                page={page} 
38              />
39            ))}
40          </PaginationPageGroup>
41          <PaginationNext>Next</PaginationNext>
42        </PaginationContainer>
43      </Pagination>
44    </ChakraProvider>
45  );
46};
47
48export default Demo;

Styling

The _curent prop will contain the props for the page which is currently selected All other props will apply to every other page

1<PaginationPage
2  w={7}
3  bg="red.300"
4  fontSize="sm"
5  _hover={{
6    bg: "green.300"
7  }}
8  _current={{
9    w: 7,
10    bg: "green.300"
11    fontSize: "sm"
12    _hover: {
13      bg: "blue.300"
14    },
15  }}
16>

1<PaginationPrevious
2  bg="blue.500"
3  w="20rem"
4  //...any button prop
5>
6  Previous
7</PaginationPrevious>

1<PaginationNext
2  w={7}
3  bg="red.300"
4  fontSize="sm"
5  //...any button prop
6>
7  Next
8</PaginationNext>

1<PaginationContainer
2  bg="blue.500"
3  w="full"
4  //...any flex prop
5>
6  ...
7</PaginationContainer>

1<PaginationPageGroup
2  bg="blue.500"
3  w="full"
4  //...any stack prop
5>
6  ...
7</PaginationPageGroup>

Disabling

It's provided a commodity disable prop to disable/enable all your pagination components at once

1const { isDisabled, setIsDisabled } = usePagination({
2  initialState: { isDisabled: false }
3});
4
5const handleDisableClick = () => {
6  return setIsDisabled((oldState) => !oldState);
7};
8
9<Pagination
10  isDisabled={isDisabled}
11>

Page size

It's provided a commodity page size setter and getter

1const { pageSize, setPageSize } = usePagination({
2  initialState: { pageSize: 5 },
3});
4
5const handlePageSizeChange = (event: ChangeEvent<HTMLSelectElement>) => {
6  const pageSize = Number(event.target.value);
7
8  setPageSize(pageSize);
9};

Limits

You can trim the ammount of pages you show by passing both limits at the same time You need to pass them both, otherwise no limits will be applied

1const { pages } = usePagination({
2  limits: {
3    outer: outerLimit,
4    inner: innerLimit,
5  },
6});

Separator

Additionaly, you can customize the separator component used when limits are defined

1<PaginationPageGroup separator={<PaginationSeparator _hover={{ bg: 'purple.500' }} bg='teal.500'>}>
2  {pages.map((page: number) => (
3    <PaginationPage key={`pagination_page_${page}`} page={page} />
4  ))}
5</PaginationPageGroup>

Offset

It's possible that the API for the pagination you are consuming works with an offset One it's calculated and provided for you using the pageSize and currentPage values

This is calculated with the next formula:

[currentPage * pageSize - pageSize]

currentPage === 1 && pageSize === 5 // offset = 0;
currentPage === 2 && pageSize === 5 // offset = 5;
currentPage === 3 && pageSize === 5 // offset = 10;

1const { offset, pageSize } = usePagination({
2  initialState: { pageSize: 5 },
3});
4
5fetchUsingOffset(pageSize, offset).then((data) => {
6  // use data
7});

Total

Keep in mind that if you know the total amount of items of the requested endpoint, which is not a strange thing to be returned, you can use that to generate the pages for you

1const { pages, pagesCount } = usePaginator({
2  total: 4021,
3  initialState: { pageSize: 5 }
4});
5
6<Pagination
7  pagesCount={pagesCount}
8>
9
10<PaginationPageGroup>
11  {pages.map((page: number) => (
12    <PaginationPage key={`pagination_page_${page}`} page={page} />
13  ))}
14</PaginationPageGroup>

Full usage example

In this example you can see all the possible features provided by the library being applied to show 10 pokemons names, with the ability to play with the page size and disable state

1import React, { FC, ChangeEvent, useEffect, useState } from "react";
2import { Grid, Center, Select, Text, Button, Stack } from "@chakra-ui/react";
3import {
4  Pagination,
5  usePagination,
6  PaginationPage,
7  PaginationNext,
8  PaginationPrevious,
9  PaginationPageGroup,
10  PaginationContainer,
11  PaginationSeparator,
12} from "@ajna/pagination";
13
14const fetchPokemons = async (
15  pageSize: number,
16  offset: number
17): Promise<any> => {
18  return await fetch(
19    `https://pokeapi.co/api/v2/pokemon?limit=${pageSize}&offset=${offset}`
20  ).then(async (res) => await res.json());
21};
22
23const Full: FC = () => {
24  // states
25  const [pokemonsTotal, setPokemonsTotal] = useState<number | undefined>(
26    undefined
27  );
28  const [pokemons, setPokemons] = useState<any[]>([]);
29
30  // constants
31  const outerLimit = 2;
32  const innerLimit = 2;
33
34  // pagination hook
35  const {
36    pages,
37    pagesCount,
38    offset,
39    currentPage,
40    setCurrentPage,
41    setIsDisabled,
42    isDisabled,
43    pageSize,
44    setPageSize,
45  } = usePagination({
46    total: pokemonsTotal,
47    limits: {
48      outer: outerLimit,
49      inner: innerLimit,
50    },
51    initialState: {
52      pageSize: 5,
53      isDisabled: false,
54      currentPage: 1,
55    },
56  });
57
58  // effects
59  useEffect(() => {
60    fetchPokemons(pageSize, offset)
61      .then((pokemons) => {
62        setPokemonsTotal(pokemons.count);
63        setPokemons(pokemons.results);
64      })
65      .catch((error) => console.error("App =>", error));
66  }, [currentPage, pageSize, offset]);
67
68  // handlers
69  const handlePageChange = (nextPage: number): void => {
70    // -> request new data using the page number
71    setCurrentPage(nextPage);
72    console.log("request new data with ->", nextPage);
73  };
74
75  const handlePageSizeChange = (
76    event: ChangeEvent<HTMLSelectElement>
77  ): void => {
78    const pageSize = Number(event.target.value);
79
80    setPageSize(pageSize);
81  };
82
83  const handleDisableClick = (): void => {
84    setIsDisabled((oldState) => !oldState);
85  };
86
87  return (
88    <Stack>
89      <Pagination
90        pagesCount={pagesCount}
91        currentPage={currentPage}
92        isDisabled={isDisabled}
93        onPageChange={handlePageChange}
94      >
95        <PaginationContainer
96          align="center"
97          justify="space-between"
98          p={4}
99          w="full"
100        >
101          <PaginationPrevious
102            _hover={{
103              bg: "yellow.400",
104            }}
105            bg="yellow.300"
106            isDisabled
107            onClick={() => console.warn("I'm clicking the previous")}
108          >
109            <Text>Previous</Text>
110          </PaginationPrevious>
111          <PaginationPageGroup
112            isInline
113            align="center"
114            separator={
115              <PaginationSeparator
116                isDisabled
117                onClick={() => console.warn("I'm clicking the separator")}
118                bg="blue.300"
119                fontSize="sm"
120                w={7}
121                jumpSize={11}
122              />
123            }
124          >
125            {pages.map((page: number) => (
126              <PaginationPage
127                w={7}
128                bg="red.300"
129                key={`pagination_page_${page}`}
130                page={page}
131                onClick={() => console.warn("Im clicking the page")}
132                fontSize="sm"
133                _hover={{
134                  bg: "green.300",
135                }}
136                _current={{
137                  bg: "green.300",
138                  fontSize: "sm",
139                  w: 7,
140                }}
141              />
142            ))}
143          </PaginationPageGroup>
144          <PaginationNext
145            _hover={{
146              bg: "yellow.400",
147            }}
148            bg="yellow.300"
149            onClick={() => console.warn("I'm clicking the next")}
150          >
151            <Text>Next</Text>
152          </PaginationNext>
153        </PaginationContainer>
154      </Pagination>
155      <Center w="full">
156        <Button
157          _hover={{
158            bg: "purple.400",
159          }}
160          bg="purple.300"
161          onClick={handleDisableClick}
162        >
163          Disable ON / OFF
164        </Button>
165        <Select ml={3} onChange={handlePageSizeChange} w={40}>
166          <option value="10">10</option>
167          <option value="25">25</option>
168          <option value="50">50</option>
169        </Select>
170      </Center>
171      <Grid
172        gap={3}
173        mt={20}
174        px={20}
175        templateColumns="repeat(5, 1fr)"
176        templateRows="repeat(2, 1fr)"
177      >
178        {pokemons?.map(({ name }) => (
179          <Center key={name} bg="green.100" p={4}>
180            <Text>{name}</Text>
181          </Center>
182        ))}
183      </Grid>
184    </Stack>
185  );
186};
187
188export default Full;