# Pagination (`pagination`) - SignalOS widget

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

- **Version:** 0.2.0
- **Kind:** widget · **Category:** data-display
- **Install:** `npx shadcn@latest add @signalos/pagination`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/button, @signalos/select
- **npm dependencies:** lucide-react@^1.7.0
- **Files installed:** `src/components/widgets/pagination/Pagination.tsx`, `src/components/widgets/pagination/Pagination.types.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import { Pagination } from "@/components/widgets/pagination/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 | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `page` | `number` | yes | - | Current page (1-indexed). |
| `pageSize` | `number` | yes | - | Number of items per page. |
| `total` | `number` | yes | - | Total record count across all pages. |
| `totalPages` | `number` | yes | - | Total number of pages. |
| `pageSizeOptions` | `number[] \| undefined` | no | `[5, 10, 25, 50]` | Available page size options. |
| `onPageChange` | `(page: number) => void` | yes | - | Callback when page number changes. |
| `onPageSizeChange` | `(pageSize: number) => void` | yes | - | Callback when page size changes. |
| `rowsPerPageLabel` | `string \| undefined` | no | `"Rows per page:"` | Label for rows per page selector. |
| `showRecordCount` | `boolean \| undefined` | no | `true` | Whether to show the record count display. |
| `recordCountFormat` | `((start: number, end: number, total: number) => string) \| undefined` | no | - | Custom record count format. Receives (start, end, total). |
| `className` | `string \| undefined` | no | - | Merged onto the root element. |
| `data-testid` | `string \| undefined` | no | - | 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`. |

## 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
  `Pagination`s 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