Components

Pagination

Page or cursor navigation under tables and lists, with a page size choice.

Storybook: Storybook
Source: Source

The example below loads live from Storybook; open it in Storybook for the controls.

Live example, StorybookOpen in Storybook

Default

Pagination does not hold the page; you manage it with page and onPageChange. On a long list it shows the first and last page, the current page and its neighbours; skipped pages are marked with …. Below 1024 px the page numbers are hidden and previous, next and a “4 / 20” counter remain.

import { Pagination } from '@bigbang/ui';
import { useState } from 'react';

export default function Default() {
  const [page, setPage] = useState(4);
  return <Pagination page={page} pageCount={20} onPageChange={setPage} />;
}

Sizes

Items are 36 px high at md and 32 px at sm. Use sm under dense tables.

import { Pagination } from '@bigbang/ui';
import { useState } from 'react';

export default function Sizes() {
  const [page, setPage] = useState(4);
  return (
    <div className="flex flex-col gap-3xl">
      <Pagination size="sm" page={page} pageCount={20} onPageChange={setPage} />
      <Pagination size="md" page={page} pageCount={20} onPageChange={setPage} />
    </div>
  );
}

Page size and summary

Pass pageSize, pageSizeOptions and onPageSizeChange to show the “Per page” choice. totalCount adds the “21-40 / 345” summary. When the size changes, reset the page to 1; the old page may no longer exist.

import { Pagination } from '@bigbang/ui';
import { useState } from 'react';

const total = 345;

export default function WithPageSize() {
  const [page, setPage] = useState(1);
  const [pageSize, setPageSize] = useState(20);
  return (
    <Pagination
      page={page}
      pageCount={Math.ceil(total / pageSize)}
      onPageChange={setPage}
      pageSize={pageSize}
      pageSizeOptions={[10, 20, 50]}
      onPageSizeChange={(next) => {
        setPageSize(next);
        setPage(1);
      }}
      totalCount={total}
    />
  );
}

Cursor mode

When the number of pages is unknown, use mode="cursor". It has only previous and next; there are no page numbers or counter. When totalCount is known, “Total 345” is shown.

import { Pagination } from '@bigbang/ui';
import { useState } from 'react';

export default function Cursor() {
  const [index, setIndex] = useState(0);
  return (
    <Pagination
      mode="cursor"
      hasPrevious={index > 0}
      hasNext={index < 4}
      onPrevious={() => setIndex((value) => value - 1)}
      onNext={() => setIndex((value) => value + 1)}
    />
  );
}

Links

When the page is kept in the URL, pass getPageHref. The page, previous and next controls become links instead of buttons; onPageChange is still called.

import { Pagination } from '@bigbang/ui';
import { useState } from 'react';

export default function Links() {
  const [page, setPage] = useState(3);
  return <Pagination page={page} pageCount={12} onPageChange={setPage} getPageHref={(next) => `#page-${next}`} />;
}

Light and dark mode

Pagination takes its colours from action, surface and border tokens.

import { Pagination } from '@bigbang/ui';
import { useState } from 'react';

export default function Default() {
  const [page, setPage] = useState(4);
  return <Pagination page={page} pageCount={20} onPageChange={setPage} />;
}