Paginact NPM | npm.io

Paginact

This package offers only one thing— a custom React hook— usePagination() hook. This hook handles all the stateful logic needed to implement (Offset-based) Pagination in your React/React Native app.

Installation

npm install paginact

Or,

yarn add paginact

Usage

import usePagination from "paginact";


  const {
    totalNumberOfItems,
    itemsPerPage,
    numberOfPages,
    firstPageIndex,
    lastPageIndex,
    currentPageIndex,
    offset,
    startItemIndexOnCurrentPage,
    endItemIndexOnCurrentPage,
    previousPageIndex,
    nextPageIndex,
    setTotalNumberOfItems, //Use it to set Total Number of Items
    setItemsPerPage, //Use it to set Number of Items per Page
    setCurrentPageIndex, //Use it to set the Index of Current Page
  } = usePagination(97, 10, 1);
//Pagination, initialized for 97 items, and 10 items per page with current page number 1.

Note: Both Page Indices and Item Indices here start from 1, not 0.

Example

I used this ugly paginact-test project (bootstrapped by create-react-app) to test Paginact.

You may want to look at src/App.js of the project (shown below).

import usePagination from "paginact";

function App() {
  const {
    totalNumberOfItems,
    itemsPerPage,
    numberOfPages,
    firstPageIndex,
    lastPageIndex,
    currentPageIndex,
    offset,
    startItemIndexOnCurrentPage,
    endItemIndexOnCurrentPage,
    previousPageIndex,
    nextPageIndex,
    setTotalNumberOfItems,
    setItemsPerPage,
    setCurrentPageIndex,
  } = usePagination(97, 10, 1);
  return (
    <>
      <label>Total</label>
      <input
        type="number"
        onChange={(event) =>
          setTotalNumberOfItems(parseInt(event.target.value))
        }
      />
      <label>Items Per Page</label>
      <input
        type="number"
        onChange={(event) => setItemsPerPage(parseInt(event.target.value))}
      />
      <label>Current Page</label>
      <input
        type="number"
        onChange={(event) => setCurrentPageIndex(parseInt(event.target.value))}
      />
      <div>
        Items: {startItemIndexOnCurrentPage}-{endItemIndexOnCurrentPage}
      </div>
      <div>current page: {currentPageIndex}</div>
      <div>offset: {offset}</div>
      <div>first page: {firstPageIndex}</div>
      <div>last page: {lastPageIndex}</div>
      <div>previous page: {previousPageIndex}</div>
      <div>next page: {nextPageIndex}</div>
      <div>total page: {numberOfPages}</div>
      <div>items per page: {itemsPerPage}</div>
      <div>total item: {totalNumberOfItems}</div>
    </>
  );
}

export default App;

API Reference

usePagination()

usePagination(
  initialTotalNumberOfItems = 0,
  initialItemsPerPage = 0,
  initialCurrentPageIndex = null
)

Parameter	Type	Description
`initialTotalNumberOfItems`	`number`	Must be a non-negative integer
`initialItemsPerPage`	`number`	Must be a non-negative integer. If `initialTotalNumberOfItems` is non-zero, this must be non-zero too, and if not provided accordingly, this is set to `1` by default
`initialCurrentPageIndex`	`number`	Must be a positive integer or `null` by default. If invalid against `initialTotalNumberOfItems` and `initialItemsPerPage`, this is set to `1`.

This hook returns a single object. In the Usage section above is a comprehensive destructuring of the object, showing all the keys of the object.

The case when `totalNumberOfItems` is `0`

Either through initialTotalNumberOfItems parameter of usePagination() hook, or through setTotalNumberOfItems, whenever totalNumberOfItems is 0, here is what we get—

{
  totalNumberOfItems: 0,
  itemsPerPage: 0,
  numberOfPages: 0,
  firstPageIndex: null,
  lastPageIndex: null,
  currentPageIndex: null,
  offset: 0,
  startItemIndexOnCurrentPage: null,
  endItemIndexOnCurrentPage: null,
  previousPageIndex: null,
  nextPageIndex: null,
}

Keys of the Object returned by `usePagination()` hook

Key	Type	Description
`totalNumberOfItems`	`number`	A non-negative integer
`setTotalNumberOfItems`	`function`	Takes a single non-negative integer `number` type argument as the new value of `totalNumberOfItems`. Throws error on invalid argument.
`itemsPerPage`	`number`	A non-negative integer. `0` only when `totalNumberOfItems` is `0`.
`setItemsPerPage`	`function`	Takes a single positive integer `number` type argument as the new value of `itemsPerPage`. Throws error on invalid argument.
`currentPageIndex`	`number` or `null`	A positive integer, or `null` only when `totalNumberOfItems` is `0`.
`setCurrentPageIndex`	`function`	Takes a single positive integer `number` type argument as the new value of `currentPageIndex`. The argument must not be greater than `numberOfPages` described below. Throws error on invalid argument.
`numberOfPages`	`number`	A non-negative integer, or `0` only when `totalNumberOfItems` is `0`.
`firstPageIndex`	`number` or `null`	`1`, or `null` only when `totalNumberOfItems` is `0`.
`lastPageIndex`	`number` or `null`	Equal to `numberOfPages`, or `null` only when `totalNumberOfItems` is `0`.
`offset`	`number`	A non-negative integer. This is the total number of items under the pages before the current page (`currentPageIndex`).
`startItemIndexOnCurrentPage`	`number` or `null`	A positive integer, or `null` when `totalNumberOfItems` is `0`.
`endItemIndexOnCurrentPage`	`number` or `null`	A positive integer, or `null` when `totalNumberOfItems` is `0`. When there is only one item on a page, this is equal to `startItemIndexOnCurrentPage`. When building UI, you might want to consider this case of equality.
`previousPageIndex`	`number` or `null`	A positive integer, or `null` there is no previous page.
`nextPageIndex`	`number` or `null`	A positive integer, or `null` there is no next page.