2.0.0 • Published 6 months ago

als-pagination v2.0.0

Weekly downloads
-
License
MIT
Repository
-
Last release
6 months ago

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
2.0.0

6 months ago

1.0.0

7 months ago