Cursor Pager

Install

pnpm exec vegastack-design verify cursor-pager

pnpm dlx shadcn@4.21.0 add @vegastack/cursor-pager

Usage

import { CursorPager } from "@/components/ui/cursor-pager";

const [history, setHistory] = React.useState<(string | null)[]>([]);
const [cursor, setCursor] = React.useState<string | null>(null);

<CursorPager
  label={`Rows ${history.length * 100 + 1}–${history.length * 100 + page.rows.length}`}
  hasPrevious={history.length > 0}
  hasNext={page.nextCursor != null}
  onPrevious={() => {
    setCursor(history.at(-1) ?? null);
    setHistory(history.slice(0, -1));
  }}
  onNext={() => {
    setHistory([...history, cursor]);
    setCursor(page.nextCursor);
  }}
/>;

A keyset-paged list knows whether a page exists on either side and what the current page holds, but not how many pages there are or where page 7 starts. CursorPager shows exactly that: a range label at the leading edge, and Previous and Next. It is controlled and owns no cursors — the host keeps the cursor history (the stack of cursors it came through) and fetches.

DataGrid's pagedMode renders it under the grid, for people who page instead of scroll. For a list with a total and page numbers, reach for DataListPager.

Examples

At the first page, and while a page loads

At either end the button stays in the tab order with aria-disabled; while loading both hold still and the pager is aria-busy.

API Reference

Accessibility

• A navigation landmark named Pagination (aria-label renames it).
• Previous and Next are buttons that stay focusable at either end (aria-disabled), rather than disappearing.
• A new label string is announced politely through one live region; the label on screen at first render is not.

Do / Don't