Data List Pager

InstallCopy Anchor Link

pnpm exec vegastack-design verify data-list-pager

pnpm dlx shadcn@4.21.0 add @vegastack/data-list-pager

UsageCopy Anchor Link

import { DataList } from "@/components/ui/data-list";
import { DataListPager } from "@/components/ui/data-list-pager";

const [page, setPage] = React.useState(1);
const [pageSize, setPageSize] = React.useState(15);

<DataList
  columns={columns}
  data={rows.slice((page - 1) * pageSize, page * pageSize)}
  getRowId={(row) => row.id}
  footer={
    <DataListPager
      page={page}
      pageSize={pageSize}
      total={rows.length}
      onPageChange={setPage}
      onPageSizeChange={(size) => {
        setPageSize(size);
        setPage(1);
      }}
    />
  }
/>;

DataListPager is built for DataList's footer slot. It composes Pagination and Select and adds no visual primitive of its own: a range summary in tabular numerals ("1–15 of 40"), a rows-per-page chooser, and a windowed page list with Previous and Next.

It is controlled and owns no data. The host holds page (1-based) and pageSize, slices or fetches the rows, and passes total. A server-paged host sends limit = pageSize and offset = (page - 1) * pageSize. Changing the page size only reports the request — whether that returns to page 1 (as above) or keeps the first visible row is the host's policy.

ExamplesCopy Anchor Link

Many pagesCopy Anchor Link

With more than seven pages the list collapses into a window: the first and last page, the current page and its neighbours, and an ellipsis for each collapsed run.

A single pageCopy Anchor Link

When every row fits on one page the page controls are hidden. The range and the rows-per-page chooser stay, so a reader can still widen or narrow the page. An empty list reads "0 of 0".

Narrow containersCopy Anchor Link

The page list follows the pager's own width, not the viewport's, and never wraps — a wrapped run of page numbers reads as two lists. It changes layout instead (data-layout on the root), while the range and the rows-per-page chooser wrap onto their own lines above it:

Width picks the starting layout for page numbers of up to two digits. A number slot is at least 32px and grows to hold its number, so a longer page count can outgrow that layout (a three-digit last page already makes the compact list about 241px); the pager then measures every page item against its own box, with no tolerance, and steps down one layout at a time until the page list fits, before first paint. The check is re-taken on any change to the pager's width, however small, and whenever an element of the page list changes size on its own — a web font swapping in, say — so a late font cannot push Next outside. At the last step the position shortens to N / M (data-short on data-slot="data-list-pager-position") and truncates if it still has no room, while assistive technology always hears Page N of M. So the page list never scrolls sideways at any page count. The range and the rows-per-page chooser are single lines that do not break; at a seven-digit total they need about 200px, which is the pager's practical floor. The server render is minimal, and the client corrects it before first paint.

Page sizesCopy Anchor Link

pageSizes sets the choices (default [15, 30, 50]). A pageSize that is not in the list is added to it, so the chooser always shows the current value.

Numbers that are not numbers render a sane state rather than NaN: a total that is NaN, undefined (a count still loading) or negative reads as 0 ("0 of 0", no page controls); a page that is not finite reads as 1; and a pageSize that is not a positive number — 0 included — shows the first pageSizes entry and is never added to the chooser. pageSizeLabel renames the chooser — it is both the visible label and the accessible name.

<DataListPager
  page={page}
  pageSize={pageSize}
  total={total}
  pageSizes={[10, 25, 100]}
  pageSizeLabel="Invoices per page"
  onPageChange={setPage}
  onPageSizeChange={setPageSize}
/>

Without page sizeCopy Anchor Link

Omit onPageSizeChange for a fixed page size: the pager shows the range and the page controls, and no rows-per-page chooser.

API ReferenceCopy Anchor Link

pagerWindow(current, pages) is exported too: it returns the windowed page list the pager renders (number | "ellipsis" entries), for a host that draws its own page controls.

AccessibilityCopy Anchor Link

• The page list is a navigation landmark named Pagination. Its controls are buttons — they change the page in place rather than navigating — each page named Go to page N, with the current page marked aria-current="page".
• Previous and Next stay in the tab order at either end. They carry aria-disabled="true" and do nothing when activated, rather than disappearing or dropping pointer events.
• The rows-per-page Select is named by its visible label (aria-labelledby), so the name a screen reader speaks is the text on screen.
• A page change announces the new range politely (Showing 16–30 of 40) through one live region mounted for the pager's life; the range on screen at first render is not announced.

Do / Don'tCopy Anchor Link