Chakra paginator

Deprecation notice: this package has been moved to @ajna/pagination

Table of Contents

• Version
• Installation
• Demo with all options applied
• Components API
  • Paginator
  • usePaginator
  • Container
  • PageGroup
  • Previous
  • Next
• Usage
  • Minimal
  • Styling
  • Disabling
  • Page size
  • Limits
  • Offset
  • Pages quantity
  • Full usage example

Version

Installation

npm

1npm i chakra-paginator

Yarn

1yarn add chakra-paginator

Demo with all options applied

Check it out in this Sandbox

Components API

Paginator

Prop	Description	Type	Default	Required
pagesQuantity	The total number of pages, calculated based on Backend data	number	0	yes
onPageChange	On change handler which returns the last selected page	(nextPage: number) => void		yes
isDisabled	Disables all of the pagination components. You can always disable each individual component via the isDisabled prop, as the components render HTML buttons	boolean	false	no
activeStyles	The styles of the active page button	ButtonProps	{}	no
normalStyles	The styles of the inactive page buttons	ButtonProps	{}	no
separatorStyles	The styles of the separator wrapper	ButtonProps	{}	no
outerLimit	The amount of pages to show at the start and at the end	number	0	no
innerLimit	The amount of pages to show from the currentPage backwards and forward	number	0	no
currentPage	Manually set the currentPage of the pagination	number	1	no

usePaginator

Options

Prop	Description	Type	Default	Required
total	The total amount of items obtained from a Backend call	number	0	no
initialState	Initial states for pagination values	InitialState		yes

Returned values

Prop	Description	Type	Default	Required
offset	Generic offset value generated if pageSize is provided	number	0	no
pagesQuantity	Automatically calculated based on total and pageSize. Keep in mind that you can pass this directly to Paginator. This is a commodity if you know the total	number	0	no
currentPage	The current page number	number		yes
pageSize	The amount of items per page	number	10	no
isDisabled	Disabled or enables all the pagination components	boolean	false	no
setPageSize	A setter for the pageSize value	Dispatch<SetStateAction >		no
setIsDisabled	A setter for the isDisabled value	Dispatch<SetStateAction >		no
setCurrentPage	A setter for the currentPage value	Dispatch<SetStateAction >		yes

Container

Container is a _Flex_ component, so any _FlexProps_ are accepted

PageGroup

PageGroup is a _Stack_ component, so any _StackProps_ are accepted

Previous

Previous is a _Button_ component, so any _ButtonProps_ are accepted

Next

Next is a _Button_ component, so any _ButtonProps_ are accepted

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  Paginator,
5  Container,
6  Previous,
7  Next,
8  PageGroup,
9  usePaginator
10} from "chakra-paginator";
11
12const Demo: FC = () => {
13  const pagesQuantity = 12;
14  const { currentPage, setCurrentPage } = usePaginator({
15    initialState: { currentPage: 1 }
16  });
17
18  return (
19    <ChakraProvider>
20      <Paginator
21        pagesQuantity={pagesQuantity}
22        currentPage={currentPage}
23        onPageChange={setCurrentPage}
24      >
25        <Container align="center" justify="space-between" w="full" p={4}>
26          <Previous>
27            Previous
28            {/* Or an icon from `react-icons` */}
29          </Previous>
30          <PageGroup isInline align="center" />
31          <Next>
32            Next
33            {/* Or an icon from `react-icons` */}
34          </Next>
35        </Container>
36      </Paginator>
37    </ChakraProvider>
38  );
39};
40
41export default Demo;

1+ From here on, the examples are only partial. You can think of them as modules you can add to the previous component
2+ Merge them togheter and you would be adding the given functionality

Styling

Add styles to the possible components inside PageGroup

First: the styles for the unselected and selected page buttons
Second: the styles for the separator button

1const normalStyles: ButtonProps = {
2  w: 7,
3  bg: "red.300"
4  fontSize: "sm"
5  _hover: {
6    bg: "green.300"
7  },
8};
9
10const activeStyles: ButtonProps = {
11  w: 7,
12  bg: "green.300"
13  fontSize: "sm"
14  _hover: {
15    bg: "blue.300"
16  },
17};
18
19const separatorStyles: ButtonProps = {
20  w: 7,
21  bg: "green.200"
22};
23
24<Paginator
25  activeStyles={activeStyles}
26  normalStyles={normalStyles}
27  separatorStyles={separatorStyles}
28>

Disabling

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

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

Page size

It's provided a commodity page size setter and getter

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

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 outerLimit = 2;
2const innerLimit = 2;
3
4<Paginator
5  outerLimit={outerLimit}
6  innerLimit={innerLimit}
7>

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 } = usePaginator({
2  initialState: { pageSize: 5 }
3});
4
5fetchUsingOffset(pageSize, offset).then((data) => {
6  // use data
7});

Pages quantity

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 quantity value for you

1const { pagesQuantity } = usePaginator({
2  total: 4021,
3  initialState: { pageSize: 5 }
4});
5
6<Paginator
7  pagesQuantity={pagesQuantity}
8>

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 {
3  Grid,
4  Center,
5  Select,
6  ButtonProps,
7  Text,
8  Button,
9  ChakraProvider
10} from "@chakra-ui/react";
11import {
12  Paginator,
13  Container,
14  Previous,
15  usePaginator,
16  Next,
17  PageGroup
18} from "chakra-paginator";
19
20const fetchPokemons = (pageSize: number, offset: number) => {
21  return fetch(
22    `https://pokeapi.co/api/v2/pokemon?limit=${pageSize}&offset=${offset}`
23  ).then((res) => res.json());
24};
25
26const Demo: FC = () => {
27  // states
28  const [pokemonsTotal, setPokemonsTotal] = useState<number | undefined>(
29    undefined
30  );
31  const [pokemons, setPokemons] = useState<any[]>([]);
32
33  // constants
34  const outerLimit = 2;
35  const innerLimit = 2;
36
37  const {
38    pagesQuantity,
39    offset, 
40    currentPage,
41    setCurrentPage,
42    setIsDisabled,
43    isDisabled,
44    pageSize,
45    setPageSize
46  } = usePaginator({
47    total: pokemonsTotal,
48    initialState: {
49      pageSize: 5,
50      isDisabled: false,
51      currentPage: 1
52    }
53  });
54
55  // effects
56  useEffect(() => {
57    fetchPokemons(pageSize, offset).then((pokemons) => {
58      setPokemonsTotal(pokemons.count);
59      setPokemons(pokemons.results);
60    });
61  }, [currentPage, pageSize, offset]);
62
63  // styles
64  const baseStyles: ButtonProps = {
65    w: 7,
66    fontSize: "sm"
67  };
68
69  const normalStyles: ButtonProps = {
70    ...baseStyles,
71    _hover: {
72      bg: "green.300"
73    },
74    bg: "red.300"
75  };
76
77  const activeStyles: ButtonProps = {
78    ...baseStyles,
79    _hover: {
80      bg: "blue.300"
81    },
82    bg: "green.300"
83  };
84
85  const separatorStyles: ButtonProps = {
86    w: 7,
87    bg: "green.200"
88  };
89
90  // handlers
91  const handlePageChange = (nextPage: number) => {
92    // -> request new data using the page number
93    setCurrentPage(nextPage);
94    console.log("request new data with ->", nextPage);
95  };
96
97  const handlePageSizeChange = (event: ChangeEvent<HTMLSelectElement>) => {
98    const pageSize = Number(event.target.value);
99
100    setPageSize(pageSize);
101  };
102
103  const handleDisableClick = () => {
104    return setIsDisabled((oldState) => !oldState);
105  };
106
107  return (
108    <ChakraProvider>
109      <Paginator
110        isDisabled={isDisabled}
111        activeStyles={activeStyles}
112        innerLimit={innerLimit}
113        currentPage={currentPage}
114        outerLimit={outerLimit}
115        normalStyles={normalStyles}
116        separatorStyles={separatorStyles}
117        pagesQuantity={pagesQuantity}
118        onPageChange={handlePageChange}
119      >
120        <Container align="center" justify="space-between" w="full" p={4}>
121          <Previous>
122            Previous
123            {/* Or an icon from `react-icons` */}
124          </Previous>
125          <PageGroup isInline align="center" />
126          <Next>
127            Next
128            {/* Or an icon from `react-icons` */}
129          </Next>
130        </Container>
131      </Paginator>
132      <Center w="full">
133        <Button onClick={handleDisableClick}>Disable ON / OFF</Button>
134        <Select w={40} ml={3} onChange={handlePageSizeChange}>
135          <option value="10">10</option>
136          <option value="25">25</option>
137          <option value="50">50</option>
138        </Select>
139      </Center>
140      <Grid
141        templateRows="repeat(2, 1fr)"
142        templateColumns="repeat(5, 1fr)"
143        gap={3}
144        px={20}
145        mt={20}
146      >
147        {pokemons?.map(({ name }) => (
148          <Center p={4} bg="green.100" key={name}>
149            <Text>{name}</Text>
150          </Center>
151        ))}
152      </Grid>
153    </ChakraProvider>
154  );
155};
156
157export default Demo;