Pagination

v0.2.0

Reusable pagination controls with page numbers, page size selector, and record count display.

Install

npx shadcn@latest add @signalos/pagination

Requires a configured @signalos registry and a valid SIGNALOS_REGISTRY_TOKEN - get access. Registry dependencies (@signalos/tokens, @signalos/utils, @signalos/button, @signalos/select) are pulled automatically.

Preview

Example & code

pagination.example.tsx

import React, { useState } from "react"

import { Pagination } from "@/components/widgets/pagination/Pagination"

export default function PaginationExample() {
  const [page, setPage] = useState(1)
  const [pageSize, setPageSize] = useState(10)

  // Example: total items from your data source
  const total = 245

  return (
    <div className="rounded-lg border border-border/50 bg-card">
      <Pagination
        page={page}
        pageSize={pageSize}
        total={total}
        totalPages={Math.ceil(total / pageSize)}
        onPageChange={setPage}
        onPageSizeChange={(size) => {
          setPageSize(size)
          setPage(1) // Reset to first page when changing page size
        }}
      />
    </div>
  )
}

Props

PaginationProps

Prop	Type	Default	Description
page*	`number`	-	Current page (1-indexed).
pageSize*	`number`	-	Number of items per page.
total*	`number`	-	Total record count across all pages.
totalPages*	`number`	-	Total number of pages.
pageSizeOptions	`number[] \| undefined`	[5, 10, 25, 50]	Available page size options.
onPageChange*	`(page: number) => void`	-	Callback when page number changes.
onPageSizeChange*	`(pageSize: number) => void`	-	Callback when page size changes.
rowsPerPageLabel	`string \| undefined`	"Rows per page:"	Label for rows per page selector.
showRecordCount	`boolean \| undefined`	true	Whether to show the record count display.
recordCountFormat	`((start: number, end: number, total: number) => string) \| undefined`	-	Custom record count format. Receives (start, end, total).
className	`string \| undefined`	-	Merged onto the root element.
data-testid	`string \| undefined`	-	Test identifier rendered as `data-testid` on the root element. Sub-parts (page-size trigger, record count, prev/next/page buttons) derive their own testid from this value, e.g. `${dataTestId}-prev-page`.

npm dependencies

lucide-react@^1.7.0

Changelog

Pagination Changelog

0.2.0

Added className and "data-testid" override props on the root element, matching the rest of the registry - the root was previously unstyleable from outside and always rendered data-testid="pagination", so two Paginations on one screen produced ambiguous testids. Sub-part testids (page-size trigger, record count, prev/next/page buttons) now derive from the root's data-testid (e.g. ${dataTestId}-prev-page); the defaults are unchanged, so this is additive.
Added aria-label={rowsPerPageLabel} to the rows-per-page Select's trigger - previously a screen-reader user tabbing to it heard only the current numeric value with no "rows per page" context.

0.1.2

Document the props interface (JSDoc feeds the catalog prop table).

0.1.1

Minor update (no functional changes).

0.1.0

Initial release.

Features:

Responsive pagination controls with page numbers and ellipsis
Configurable page size selector
Record count display with custom formatting
Previous/next navigation buttons
Smart page number display (shows relevant pages with ellipsis)
Full accessibility support with ARIA labels
Customizable labels and options