JW Paginate

1.0.4 · maintenance · verified Sun Apr 19

jw-paginate provides a standalone, framework-agnostic utility for calculating pagination logic, implemented in both JavaScript and TypeScript. It offers a pure function that, given parameters like total items, current page, page size, and maximum pages to display, returns a comprehensive object containing all necessary pagination details. This includes total pages, start and end item indices, start and end page numbers, and an array of page numbers to render in a UI. The current stable version is 1.0.4. Due to its minimalist 'pure logic' design and comprehensive feature set for its specific domain, the library has a very infrequent release cadence, with its last significant update occurring in 2018. Its primary differentiator is its complete lack of external dependencies and framework agnosticism, allowing seamless integration into any web project without introducing framework-specific couplings or unnecessary bloat. It also ships with first-class TypeScript type definitions, providing an enhanced development experience for TypeScript users.

Common errors

```
TypeError: paginate is not a function
```
cause Attempting to import `paginate` as a named export when it is a default export.

fix Change your import statement to `import paginate from 'jw-paginate';` or `const paginate = require('jw-paginate').default;` for CommonJS.
```
console.log(page.pages.length) shows 0 or incorrect number of pages
```
cause Incorrect `totalItems` value passed to the `paginate` function, often 0 or a non-positive number, or misinterpretation of `maxPages`.

fix Ensure `totalItems` is a positive integer representing the total count of all items. Verify `maxPages` is set to a reasonable number of page links you want to display, not the total number of pages.
```
Page numbers are showing up as `NaN` or unexpected values in my UI
```
cause Non-numeric or invalid values passed for `currentPage`, `pageSize`, or `maxPages`.

fix Ensure all numerical parameters passed to `paginate` are valid numbers. If values come from URL query parameters or user input, parse them to integers (e.g., `parseInt(value, 10)`) and handle potential `NaN` results before passing to the function.

Warnings

gotcha The `paginate` function returns a `startIndex` and `endIndex` which are zero-based. When using these indices to slice an array in JavaScript, `array.slice(startIndex, endIndex + 1)` is typically required to include the `endIndex` element.
Fix: Always add `+ 1` to the `endIndex` when using `Array.prototype.slice()`: `yourArray.slice(page.startIndex, page.endIndex + 1)`.
gotcha The library has seen no significant updates since 2018. While its 'pure logic' nature means it's less susceptible to breaking changes or security vulnerabilities than libraries with active dependencies, it also implies no new features or active maintenance for modern JavaScript patterns or framework integrations.
Fix: Review the source code to ensure it meets your project's standards for modern practices if relying on a long-term unmaintained library. For pure logic, this is often less of a concern.
gotcha The `paginate` function uses default parameters for `currentPage`, `pageSize`, and `maxPages`. While convenient, omitting these can lead to unexpected pagination results if you intend different values from the defaults (1, 10, 10 respectively).
Fix: Always explicitly pass all parameters to `paginate(totalItems, currentPage, pageSize, maxPages)` to ensure predictable behavior, even if some values match the defaults.

Install

npm install jw-paginate npm
yarn add jw-paginate yarn
pnpm add jw-paginate pnpm

Imports

paginate

wrong:

import { paginate } from 'jw-paginate'; // paginate is a default export
const paginate = require('jw-paginate'); // CommonJS import pattern

correct:

import paginate from 'jw-paginate';

The main pagination function is exported as the default export. For TypeScript users, type definitions are included.

PaginateResult
```
import paginate, { PaginateResult } from 'jw-paginate';
```
While `PaginateResult` is a type, it's a common pattern to import types alongside the default export for clarity in TypeScript. It represents the shape of the object returned by the `paginate` function.

Quickstart

Demonstrates how to use the `paginate` function to calculate page numbers and slice a data array for a specific page. It initializes an array of items and then uses the `jw-paginate` function to determine the pagination details for a given page, logging the results.

import paginate from 'jw-paginate';

interface Item {
  id: number;
  name: string;
}

const allItems: Item[] = Array.from({ length: 150 }, (_, i) => ({
  id: i + 1,
  name: `Item ${i + 1}`
}));

// Simulate a request for page 3 with 10 items per page
const currentPage = 3;
const pageSize = 10;
const maxPagesToShow = 7;

const page = paginate(
  allItems.length, 
  currentPage, 
  pageSize, 
  maxPagesToShow
);

const pageOfItems = allItems.slice(page.startIndex, page.endIndex + 1);

console.log(`Total Items: ${page.totalItems}`);
console.log(`Total Pages: ${page.totalPages}`);
console.log(`Current Page: ${page.currentPage}`);
console.log(`Page Numbers to Display: ${page.pages}`);
console.log(`Showing items ${page.startIndex + 1} to ${page.endIndex + 1}:`);
pageOfItems.forEach(item => console.log(` - ${item.name}`));

// Example: Pagination for a different scenario
const anotherPage = paginate(50, 1, 5, 5);
console.log('\n--- Another Pagination Example ---');
console.log(`Total Pages: ${anotherPage.totalPages}`);
console.log(`Page Numbers: ${anotherPage.pages}`);

view raw JSON →