Skip to main content

Pagination

Responsive pagination component for React. Just give it a total number of items and the current offset. It then calls a handler with the new offset as needed.

pagination component

Features​

  • Lightweight UI component. Doesn't care about data, caching or state. Send it the total items and current offset, and it renders the correct interface.
  • Responsive, with a container query to show the right amount of pages
  • Gracefully supports unlimited pages
  • Automatically hides next/prev buttons when not needed
  • Customizable labels
  • Default CSS with light/dark mode available
  • CSS module support can override internal styles with a custom module

Demo​

https://npm-library-demo.vercel.app/pagination

Install​

npm install @unleashit/pagination

Example​

import React from 'react';
import Pagination from '@unleashit/pagination';
import Articles from './Articles';
import { getTotalRowsFromDB, getPageFromDB } from './api';

const perPage = 10;

function PaginationDemo() {
  // The main thing you have to do is keep track of the changed offset
  // Pagination doesn't care about the list data,
  // only the current offset and total number of items
  const [totalRows, setTotalRows] = useState<number>();
  const [data, setData] = useState<any[]>();
  const [offset, setOffset] = useState(0);

  useEffect(() => {
    // Basic example without caching or error handling
    Promise.all([
      // example to get the count(*) from the DB
      getTotalRowsFromDB(),
      // example to get a page of data starting at the offset
      // and ending with the perPage amount
      getPageFromDB({ offset, limit: perPage }),
    ]).then(([total, page]) => {
      setTotalRows(total);
      setData(page);
    });
  }, [offset]);

  // handler is called whenever the user clicks on a page, next or prev buttons
  // and is provided the new offset corresponding with the button the user clicked.
  // For example, if perPage is set to 10 and the user clicks page 3,
  // the handler will be called with 20 (page 1 = 0, page 2 = 10, page 3 = 20, etc.).
  const paginationHandler = (newOffset: number) => {
    setOffset(newOffset);
  };

  if (!data) return <div>Loading...</div>;
  if (!totalRows || !data.length) return <div>No items found.</div>;

  return (
    <>
      <Articles data={data} />
      <Pagination
        currentOffset={offset}
        perPage={perPage}
        handler={paginationHandler}
        total={totalRows}
      />
    </>
  );
}

CSS​

By default, all components come with basic css styling in two formats: standard (BEM namespaced) and a CSS Module friendly version.

To use the standard version, import it like: import '@unleashit/pagination/dist/pagination.css'. Or if you are using CSS Modules you can import css from '@unleashit/pagination/dist/pagination.module.css' and provide to the cssModule prop and/or use your own custom module targeting the internal class names.

See styling-and-theming for more info.

CSS Custom Properties​

You can get pretty far without having to write any custom CSS. By supplying a cssVars prop, you can override any of the CSS variables of the default css.

See styling-and-theming for more info.

Dark mode​

Setting the darkMode prop activates dark mode.

See Dark Mode for more info.

API​

PaginationProps

export interface PaginationProps {
  currentOffset: number;
  handler: PaginationHandler;
  total: number;
  perPage?: number;
  prevLabel?: string;
  nextLabel?: string;
  darkMode?: boolean;
  cssVars?: CSSVars<typeof varNames>;
  cssModule?: Record<string, string>;
}

PaginationHandler

Handler to be called when user clicks a page or prev/next buttons. It will be provided the next offset based on their selection. Use it to change the displayed page.

export type PaginationHandler = (newOffset: number) => void;