Skip to Content
BBRICKSv0.7.4
KitLists and tables

Pager

The v3 mock's pager (.pgr / .pg): "Showing 11–20 of 304" and ‹ 1 … 4 5 6 … 31 › (pageWindow's fixed 7-item window), 36px rounded buttons (44 on touch tiers), the current one ink, the arrows mirrored in RTL; one row that never wraps, with a 5-item window under 480px (compactPageWindow). A list on one page says "N items" and shows no buttons. Pass perPage (the rows per page) for the "Showing a–b" range; without it the summary reads "Page 2 of 7 · 164 in total", since the range cannot be known.

import { Pager } from '@ergasti/bricks';

Examples

Numbered pager

With perPage it says "Showing 41–50 of 304"; the window keeps a fixed width as you move. While loading, the other page buttons are disabled.

Code
import { useState } from 'react';
import { Pager } from '@ergasti/bricks';

function Ranges() {
  const [page, setPage] = useState(5);
  return <Pager page={page} lastPage={31} total={304} perPage={10} loading={false} label="Creators" onPage={setPage} />;
}

Without a page size, and short lists

Without perPage the summary is "Page 5 of 9 · 164 in total"; a list that fits one page says "7 items" and draws no buttons.

Code
import { useState } from 'react';
import { Pager } from '@ergasti/bricks';

function Summary() {
  const [page, setPage] = useState(5);
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <Pager page={page} lastPage={9} total={164} loading={false} label="Creators" onPage={setPage} />
      <Pager page={1} lastPage={1} total={7} loading={false} label="Creators" onPage={() => {}} />
    </div>
  );
}

Props

Prop

Type

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key pager, or with the component's own prop where it has one. A {name} is a value the component fills in.

pager
KeyEnglishArabic
pages{label} pagesصفحات {label}
showingShowing {from}–{to} of {total}بنعرض {from}–{to} من {total}
summaryPage {page} of {lastPage} · {total} in totalصفحة {page} من {lastPage} · الإجمالي {total}
items2 itemsليس رقمًا عنصر
previousPrevious pageالصفحة اللي فاتت
nextNext pageالصفحة الجاية
pagePage {n}صفحة {n}

Design guidance

How the BRICKS design system uses Pager. Written in docs/content/components/Pager.md; the props above are read from the code, which wins where the two disagree.

The pagination row under a list: a "Showing 11–20 of 304" summary and ‹ numbered pages ›; use it as a DataTable's footer.

Pager is the v3 mock's .pgr / .pg. The summary sits at the start in a polite live region; the page buttons are 36px rounded squares (44px on touch screens, ≤1024px) with the current one solid ink, the arrows mirrored in RTL, all on one row that never wraps. A list that fits on one page says "7 items" and shows no buttons. Pass perPage for the "Showing a–b of n" range; without it the summary reads "Page 2 of 7 · 164 in total".

Anatomy

  1. Nav (nav.kit-pgr, aria-label="{label} pages"): flex, space-between, 14px above.
  2. Summary (span.kit-pgr-t, aria-live="polite"): 12px --ink-3.
  3. Buttons (.kit-pg): ‹ previous, page numbers (dir="ltr", current .on with aria-current="page"), "…" gaps (aria-hidden), › next.

Variants

Page window (what the numbers show) — this is fixed by the component and differs from the v3 mock:

WidthWindowExample, 31 pages
≥ 480pxpageWindow: up to 7 items. Near the start 1 2 3 4 5 … last; in the middle 1 … p−1 p p+1 … last; near the end 1 … last−4 last−3 last−2 last−1 lastpage 1: ‹ 1 2 3 4 5 … 31 ›; page 6: ‹ 1 … 5 6 7 … 31 ›; page 31: ‹ 1 … 27 28 29 30 31 ›
< 480pxcompactPageWindow: 5 itemspage 1: ‹ 1 2 3 … 31 ›; page 6: ‹ 1 … 6 … 31 ›
≤ 7 pagesEvery page‹ 1 2 3 4 5 6 7 ›

The mock's own pager() shows only the first, last and the pages next to the current one, so page 1 of 31 reads 1 2 … 31 there, where the component draws 1 2 3 4 5 … 31. The middle of the range matches (1 … 5 6 7 … 31). A single hidden page is always shown as its number, never folded into "…".

SummaryConditionEnglish
Itemsone page"7 items" / "1 item"
RangeperPage given"Showing 11–20 of 304"
Pageno perPage"Page 2 of 7 · 164 in total"

States

StateTriggerLook
First pagepage = 1‹ disabled (35 % opacity)
Last pagepage = lastPage› disabled
LoadingloadingArrows and other pages disabled; current stays
HoverpointerBorder #CFD1DA
Focus-visibleTab--focus-ring, --rasp border
Out of rangepage < 1 or > lastPageClamped
Single pagelastPage ≤ 1Summary only

Usage

<DataTable label="My creators" columns={columns} rows={list.rows} rowKey={(c) => c.id}
  footer={<Pager page={list.page} lastPage={list.lastPage} total={list.total} perPage={10}
    loading={list.loading} label="My creators" onPage={(page) => list.set({ page })} />} />

The Analytics side tables, five per page:

<Pager page={page} lastPage={3} total={15} perPage={5} loading={false} label="Best creators" onPage={setPage} />

Where it appears

Guidelines

Do

  • Pass perPage whenever you know it; the range reads better than "Page 2 of 7".
  • Scroll the list's top into view after onPage on long tables.
  • Expect the 7-item window, not the mock's tighter "1 2 … 31", in visual reviews; it is the component's intended behaviour.

Don't

  • Don't render it for lists that are not paged; pass a count text as footer instead.
  • Don't hide it while loading; it disables itself.

RTL and Arabic

  • ‹ › glyphs are flipped with scaleX(-1) under [dir='rtl']; numbers stay LTR. Summary numbers use the language's count formatting.

Tokens

--ink, --ink-3, --line, --card, --focus-ring, --rasp.

Accessibility

  • A <nav> named "{label} pages"; buttons named "Page 3", "Previous page", "Next page"; the current page has aria-current="page".
  • The summary is a polite live region, so a page change is announced.
  • Buttons are 36px on desktop and 44px on touch screens (≤1024px).

Found in the source

  • Roles in the markup: alert.
  • ARIA attributes set: aria-label, aria-live, aria-hidden, aria-current.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: BulkBar · CopyLink · CreatorCell

Source

src/kit/ListControls.tsx (line 81) on GitHub.

On this page