pagination-window

Generates a bounded "window" into a list of items for pagination.

• truncate pages around the "current" page, presenting a fixed number of pages
• view framework agnostic (though designed around React)
• exposed as simple objects in an array which can be mapped over
• translation from API paging info, e.g. offset and limit fields

Example

import React from "react";
import getPaginationWindow from "pagination-window";

export default function PaginationControl({ offset, limit, total }) {
  return (
    <div>
      {getPaginationWindow({ offset, limit, total }).map((page) => {
        if (page.type === "ellipsis") {
          return <span key={page.key}>...</span>;
        }
        const link = !page.isDisabled
          ? `?offset=${page.offset}&limit=${limit}`
          : undefined;
        const border = page.isCurrent ? "1px solid black" : undefined;
        const style = { display: "inline-block", padding: "0.3em", border };
        return (
          <a key={page.key} href={link} style={style}>
            {page.type === "page"
              ? page.number
              : page.direction === "previous"
                ? "<<"
                : ">>"}
          </a>
        );
      })}
    </div>
  );
}

API

A single function is exported from the library taking a single config object argument and returning an array of the various pagination items.

const config = { offset: 0, limit: 10, total: 20 };
getPaginationWindow(config);
// Result:
[
  {
    type: "navigation",
    key: "navigation-previous",
    isDisabled: true,
    direction: "previous",
    number: 1,
    offset: 0,
  },
  {
    type: "page",
    key: "page-1",
    isDisabled: false,
    isCurrent: true,
    number: 1,
    offset: 0,
  },
  {
    type: "page",
    key: "page-2",
    isDisabled: false,
    isCurrent: false,
    number: 2,
    offset: 10,
  },
  {
    type: "navigation",
    key: "navigation-next",
    direction: "next",
    isDisabled: false,
    number: 2,
    offset: 10,
  },
];

Config

• offset {number} The position in the list around which to create the window.
• limit {number} The number of items displayed per page.
• total {number} The total number of items in the list.

Pagination Item

Each object in the returned array is one of Page, Navigation, or Ellipsis types and has these common properties:

• type {string} The type of the pagination item (see examples for the specific value for each type).
• key {string} A key for uniquely identifying the pagination item within the current window (e.g. for React's key property).
• isDisabled {boolean} Whether the pagination item should rendered as disabled (e.g. due to having no destination).

Page and Navigation objects have the these extra properties:

• number {number} The page number linked to by this pagination item.
• offset {number} The API offset equivalent for the page linked to by this pagination item.

Page Item

A pagination item for linking to a specific page.

• isCurrent {boolean} Whether the pagination item represents the currently selected page.

{
  "type": "page",
  "key": "page-1",
  "isDisabled": false,
  "isCurrent": true,
  "number": 1,
  "offset": 0
}

Navigation Item

A pagination item for linking to a page relative to the current page. These always appear as the first and last items.

• direction {string} The direction the pagination item navigates (e.g. "previous" or "next").

{
  type: "navigation",
  key: "navigation-previous",
  isDisabled: true,
  direction: "previous",
  number: 1,
  offset: 0,
}

Ellipsis Item

A pagination item representing a discontinuity between pages. These appear once the total page count exceeds the window size.

{
  type: "ellipsis",
  key: "ellipsis-back",
  isDisabled: true,
}