# paginact

> A React Hook for Pagination

Latest version **1.1.1** (published 2025-05-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install paginact
pnpm add paginact
yarn add paginact
bun add paginact
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2025-05-18 |
| First published | 2022-11-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Rasel Parvej |
| Maintainers | raselparvej |
| Keywords | react, react native, pagination |

## Links

- npm: https://www.npmjs.com/package/paginact
- Repository: https://github.com/RaselParvejHrid/paginact
- Homepage: https://github.com/RaselParvejHrid/paginact#readme
- Issues: https://github.com/RaselParvejHrid/paginact/issues
- npm.io page: https://npm.io/package/paginact

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.1.1 (latest) — 2025-05-18
- 1.1.0 — 2025-05-18
- 1.0.3 — 2022-11-06
- 1.0.2 — 2022-11-06
- 1.0.1 — 2022-11-06
- 1.0.0 — 2022-11-05

## README

# 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 

```bash
npm install paginact
```
Or,

```bash
yarn add paginact
```
## Usage

```javascript
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](https://codesandbox.io/s/paginact-test-ywfd0g) project (bootstrapped by create-react-app) to test **Paginact**.

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

```javascript

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()

```javascript

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](#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—

```javascript

{
  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.|


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


## FAQ

#### Can I use it in React Native?

Only pure React here, so, yes, you can use it in your React Native project, too.

---
_Source: https://npm.io/package/paginact · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._