Pagination

A controlled pagination control. The consumer owns page and pageSize; the component emits onPageChange / onPageSizeChange and recomputes the visible page range from totalCount.

import { Pagination } from '@dashforge/tw';
import { useState } from 'react';

function MyList() {
  const [page, setPage] = useState(1);
  const [pageSize, setPageSize] = useState(20);

  return (
    <Pagination
      page={page}
      pageSize={pageSize}
      totalCount={1437}
      onPageChange={setPage}
      onPageSizeChange={setPageSize}
    />
  );
}

Default (full kit)

The default variant renders the full kit: summary text, page-number buttons, first / prev / next / last navigators, page-size selector, and direct jump input.

import { useState } from 'react';
import { Pagination } from '@dashforge/tw';

function Paginated() {
  const [page, setPage] = useState(3);
  const [pageSize, setPageSize] = useState(20);
  return (
    <Pagination
      page={page}
      pageSize={pageSize}
      totalCount={247}
      onPageChange={setPage}
      onPageSizeChange={setPageSize}
      pageSizeOptions={[10, 20, 50, 100]}
    />
  );
}

Variants

import { useState } from 'react';
import { Pagination, Stack } from '@dashforge/tw';

function Variants() {
  const [pageA, setPageA] = useState(5);
  const [pageB, setPageB] = useState(5);
  return (
    <Stack gap={3}>
      <Pagination page={pageA} pageSize={20} totalCount={247}
                  onPageChange={setPageA} variant="compact" />
      <Pagination page={pageB} pageSize={20} totalCount={247}
                  onPageChange={setPageB} variant="minimal" />
    </Stack>
  );
}

Sizes

Three steps (sm / md / lg) drive padding + text size on every interactive element. Pick the size that visually balances the table or list it's attached to.

import { useState } from 'react';
import { Pagination, Stack } from '@dashforge/tw';

function SizesShowcase() {
  const [pageA, setPageA] = useState(3);
  const [pageB, setPageB] = useState(3);
  const [pageC, setPageC] = useState(3);
  return (
    <Stack gap={3}>
      <Pagination page={pageA} pageSize={20} totalCount={247}
                  onPageChange={setPageA} size="sm" variant="compact" />
      <Pagination page={pageB} pageSize={20} totalCount={247}
                  onPageChange={setPageB} size="md" variant="compact" />
      <Pagination page={pageC} pageSize={20} totalCount={247}
                  onPageChange={setPageC} size="lg" variant="compact" />
    </Stack>
  );
}

Required props

Optional surface

<Pagination
  page={page}
  pageSize={pageSize}
  totalCount={totalCount}
  onPageChange={setPage}
  onPageSizeChange={setPageSize}     // omit to hide the selector
  pageSizeOptions={[10, 20, 50, 100]} // default
  siblingCount={1}                    // pages shown each side of current
  boundaryCount={1}                   // pages always shown at start/end
  showFirstLast                       // default true
  showJumpInput                       // default true (default variant only)
  disabled={false}                    // disables all interactive bits
/>

If the total set is small enough to fit within 2 * boundaryCount + 2 * siblingCount + 3 pages, no ellipsis is shown — every page button renders explicitly. So with defaults (siblingCount=1, boundaryCount=1), totals of ≤ 7 pages render all numbers directly; 8+ pages get the ellipsis layout.

i18n

All visible strings are configurable via labels. Pass the subset you need; the rest fall back to English defaults.

<Pagination
  page={page}
  pageSize={pageSize}
  totalCount={250}
  onPageChange={setPage}
  labels={{
    first: 'Inizio',
    prev:  'Indietro',
    next:  'Avanti',
    last:  'Fine',
    page:  'Pagina',
    of:    'di',
    showing: 'Mostrando',
    perPage: 'per pagina',
    goToPage: 'Vai a pagina',
  }}
/>

Default English labels:

Accessibility

• Landmark: rendered as <nav aria-label="Pagination"> — screen reader announces it as a pagination navigation region.
• Active page: marked with aria-current="page" so screen readers announce the current position.
• Buttons: every interactive element carries an aria-label (page number, "Previous", "Next", "First", "Last", "Go to page").
• Page-size selector: a real <select> element — native a11y semantics (arrow keys, Enter, screen reader announces options).
• Jump input: real <input type="number"> with min / max matching the page range. Commits on Enter or blur.

Direct page jump

In variant="default" the rightmost input lets the user jump to any page directly:

<Pagination
  page={page}
  pageSize={pageSize}
  totalCount={1437}
  onPageChange={setPage}
  showJumpInput   // default; pass `false` to hide
/>

Behavior:

• Type a number → state is held locally until commit
• Enter commits the jump
• Blur also commits (in case the user clicks away)
• Out-of-range values are clamped to [1, totalPages]
• Invalid input is silently reset

Pairing with Table / DataGrid

<Pagination> is fully controlled by design — the same page

• pageSize state can drive both a <Pagination> UI and the underlying list / table. Sprint 4.1 will ship a Table + DataGrid that explicitly compose with Pagination via the same controlled state.

const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(20);

const paginatedRows = useMemo(
  () => allRows.slice((page - 1) * pageSize, page * pageSize),
  [allRows, page, pageSize],
);

return (
  <>
    {/* Sprint 4.1 — Table coming */}
    <YourList rows={paginatedRows} />
    <Pagination
      page={page}
      pageSize={pageSize}
      totalCount={allRows.length}
      onPageChange={setPage}
      onPageSizeChange={setPageSize}
    />
  </>
);

Customization

Pagination follows the same sx + slotProps dual-override pattern as every other @dashforge/tw component. See the Customization guide for the full decision tree.

sx — outer wrapper

<Pagination sx="justify-end gap-6" {...props} />

slotProps

Available slots: root, summary, list, pageButton, activeButton, navButton, ellipsis, pageSizeSelector, jumpInput.

<Pagination
  page={page}
  pageSize={pageSize}
  totalCount={totalCount}
  onPageChange={setPage}
  slotProps={{
    activeButton: { className: 'bg-emerald-600 border-emerald-600' },
    summary: { className: 'font-mono uppercase tracking-wide' },
  }}
/>

Theme defaults

Configure <Pagination> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Pagination: {
      defaults: { variant: 'default', size: 'md' },
    },
  },
});

Configurable axes (PaginationVariantProps):

Non-visual axes (page, pageSize, totalCount, onPageChange, onPageSizeChange, pageSizeOptions, siblingCount, boundaryCount, showFirstLast, showJumpInput, disabled, labels) are per-instance — data / behavior / i18n — not theme-configurable.

Precedence chain (lowest → highest):

1. defaultVariants from the internal paginationVariants recipe (variant: 'default', size: 'md').
2. theme.components.Pagination.defaults (application-wide).
3. Instance prop (<Pagination variant="compact" size="sm" />) — wins over theme.
4. sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.Pagination.defaults autocompletes to the two axes above.

Reactivity: useComponentDefaults('Pagination') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Props

Slots & slotProps

<Pagination> is a compound component with named slots for each toolbar region. Each slot accepts a { className?: string } override via slotProps:

Use sx for a root-level class override; use slotProps when you need to reach a specific region (e.g. active button color, summary font style).

Related

• Skeleton — pair with loading placeholders during data fetch
• Customization guide — sx vs slotProps decision tree