Data List Pager

Install

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

Usage

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.

Examples

Many pages

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 page

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 containers

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 sizes

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}
/>

API Reference

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.

Accessibility

• The page controls are upstream's Pagination: a navigation landmark named pagination, each page link named Go to page N, and 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't