als-pagination

als-pagination is a lightweight JavaScript library for generating pagination data. It supports configurable navigation controls, localization, and customizable options. Perfect for implementing pagination logic in web applications.

Changelog

2.0.0

• Changed behavior for invalid currentPage:
  • Instead of throwing an error, currentPage is now adjusted to the nearest valid value.
• Improved resilience to invalid inputs.

Installation

Install the library using npm:

npm install als-pagination

Usage

Import the library and call the pagination function:

const pagination = require('als-pagination');

const result = pagination(
   { total: 100, currentPage: 4, pageSize: 10 },
   { navigation: true, back: 'previous', next: 'next' }
);

console.log(result);

Or use in browser:

<script src="/node_modules/als-pagination/pagination.js"></script>

API

pagination(pageData, options)

Parameters

1. pageData (required, object):

   • total (number): Total number of items.
   • currentPage (number): Zero-based index of the current page. If the value is out of range, it will be adjusted to the nearest valid value (0 or totalPages - 1).
   • pageSize (number): Number of items per page.

2. options (optional, object):

   • navigation (boolean, default: false):
     • If true, includes navigation buttons (back and next).
   • back (string, default: 'back'):
     • Custom text for the "back" button.
   • next (string, default: 'next'):
     • Custom text for the "next" button.

Returns

An object with the following structure:

• hrefs (array): Contains pagination links and metadata.
  • Each item is an object with:
    • text (string): The displayed text for the link/button.
    • href (string | null): URL or null if the item is not a link (e.g., current page or "...").
    • active (boolean): Indicates if the item represents the current page.
• showing (object): Information about the range of items being displayed.
  • from (number): The index of the first item on the current page.
  • to (number): The index of the last item on the current page.
  • total (number): Total number of items.

Example Output

For input:

pagination({ total: 100, currentPage: 4, pageSize: 10 }, { navigation: true });

The output:

{
  "hrefs": [
    { "text": "back", "href": "3" },
    { "text": "1", "href": "0" },
    { "text": "...", "href": null },
    { "text": "3", "href": "2", "active": false },
    { "text": "4", "href": "3", "active": false },
    { "text": "5", "href": null, "active": true },
    { "text": "6", "href": "5", "active": false },
    { "text": "7", "href": "6", "active": false },
    { "text": "...", "href": null },
    { "text": 10, "href": "9" },
    { "text": "next", "href": "5" }
  ],
  "showing": { "from": 41, "to": 50, "total": 100 }
}

Examples

Basic Pagination

const result = pagination({ total: 50, currentPage: 2, pageSize: 10 });
console.log(result);

Handling Invalid currentPage

const result = pagination({ total: 100, currentPage: -3, pageSize: 10 });
console.log(result);
// Output: { hrefs: [...], showing: { from: 1, to: 10, total: 100 } }

Navigation Buttons

const result = pagination(
   { total: 100, currentPage: 3, pageSize: 10 },
   { navigation: true }
);
console.log(result);

Custom Localization

const result = pagination(
   { total: 100, currentPage: 4, pageSize: 10 },
   { navigation: true, back: 'назад', next: 'вперед' }
);
console.log(result);

Edge Cases

• total = 0: Returns an empty array for hrefs and showing with all values set to 0.

  pagination({ total: 0, currentPage: 0, pageSize: 10 });
  // Output: { hrefs: [], showing: { from: 0, to: 0, total: 0 } }

• Invalid currentPage: If currentPage is out of range, it is automatically adjusted to the nearest valid value.

  pagination({ total: 100, currentPage: 10, pageSize: 10 });
  // Output: { hrefs: [...], showing: { from: 91, to: 100, total: 100