@stainless-code/react-paginate
v1.0.0
Published
Elegantly use custom events in React
Downloads
22
Maintainers
Readme
@stainless-code/react-paginate
Handle client-side pagination effortlessly. Simplifies the process of paginating data in your React applications, offering a fully type-safe and feature-rich experience.
Features
- Customizable Pagination: Control the page size, initial page, and thresholds with ease.
- Performance Optimized: Uses React's
useMemo
to optimize calculations. - Type-safe: Full TypeScript support for better developer experience.
- Flexible API: Exposes powerful utilities to navigate and manipulate pagination state.
Installation
npm
npm install @stainless-code/react-paginate
yarn
yarn add @stainless-code/react-paginate
pnpm
pnpm add @stainless-code/react-paginate
bun
bun add @stainless-code/react-paginate
Usage
Here's a basic example of using usePaginate
:
import { usePaginate } from "@stainless-code/react-paginate";
import React from "react";
const Example = () => {
const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
const {
page,
pageSize,
pageIndex,
pageCount,
canNextPage,
canPrevPage,
nextPage,
prevPage,
changePageSize,
} = usePaginate(items, { initialPageSize: 10, initialPageIndex: 0 });
return (
<div>
<h1>Pagination Example</h1>
<ul>
{page.map((item, idx) => (
<li key={idx}>{item}</li>
))}
</ul>
<div>
<button onClick={prevPage} disabled={!canPrevPage}>
Previous
</button>
<button onClick={nextPage} disabled={!canNextPage}>
Next
</button>
</div>
<p>
Page {pageIndex + 1} of {pageCount}
</p>
<label>
Items per page:{" "}
<select
value={pageSize}
onChange={(e) => changePageSize(Number(e.target.value))}
>
<option value={5}>5</option>
<option value={10}>10</option>
<option value={25}>25</option>
</select>
</label>
</div>
);
};
export default Example;
Typesafety
This library is built with TypeScript and offers full type-safety. All APIs and returned values are strongly typed, ensuring a great developer experience and reducing runtime errors.
API
usePaginate(items: T[], options?: UsePaginateOptions)
Parameters
| Parameter | Type | Default | Description |
| -------------------------- | -------- | ------- | ------------------------------------------------------ |
| items
| T[]
| - | The list of items to paginate. |
| options
| object
| {}
| Configuration options for pagination. |
| options.initialPageSize
| number
| 25
| Initial number of items per page. |
| options.initialPageIndex
| number
| 0
| Initial page index. |
| options.threshold
| number
| 0
| Minimum number of items required to enable pagination. |
Returns
| Property | Type | Description |
| ---------------- | ------------------------- | ----------------------------------------------------- |
| page
| T[]
| The current page of items. |
| pageSize
| number
| The number of items per page. |
| pageIndex
| number
| The current page index. |
| pageCount
| number
| Total number of pages. |
| canNextPage
| boolean
| Whether navigation to the next page is possible. |
| canPrevPage
| boolean
| Whether navigation to the previous page is possible. |
| nextPage
| () => void
| Navigate to the next page. |
| prevPage
| () => void
| Navigate to the previous page. |
| firstPage
| () => void
| Navigate to the first page. |
| lastPage
| () => void
| Navigate to the last page. |
| changePage
| (index: number) => void
| Change to a specific page by index. |
| changePageSize
| (size: number) => void
| Change the number of items per page. |
| resetPage
| () => void
| Reset to the first page. |
| shouldPaginate
| boolean
| Whether pagination is enabled based on the threshold. |
paginate<T>(items: T[], pageSize: number, pageIndex: number): T[]
This function divides the given list of items into pages, and returns the items for the specified page.
items
: An array of items (typeT[]
) that you want to paginate.pageSize
: The number of items per page.pageIndex
: The zero-based index of the page to return.
Example Usage:
const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const pageSize = 3;
const pageIndex = 2;
const pageItems = paginate(items, pageSize, pageIndex);
// Output: [7, 8, 9]
getPageCount<T>(items: T[], pageSize: number): number
This function calculates the total number of pages required to paginate the given list of items, based on the page size.
items
: An array of items (typeT[]
) to paginate.pageSize
: The number of items per page.
Example Usage:
const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const pageSize = 3;
const totalPages = getPageCount(items, pageSize);
// Output: 4
Contributing
Feel free to submit issues or pull requests to improve the library. Every bit of help is appreciated. 💖
Read the contribution guidelines.