# Pagination

> Footer of a list or table: rows per page, the range shown ("11–20 of 134") and first, previous, next and last buttons.

Source: https://ui.jcsoftdev.com/docs/components/pagination

Footer of a list or table: rows per page, the range shown ("11–20 of 134") and first, previous,
next and last buttons. Pages are 1-based. It does not slice your rows: use `page` and `pageSize`
to do that, or to request the page from your API. Changing the page size returns to page 1.

## Import

```ts
import { Pagination } from "@jcsoftdev/ui/containers";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/containers/pagination`.

## Usage

```tsx
<Pagination total={134} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `total` * | `number` |  | Total rows across every page. |
| `page` | `number` |  | Controlled 1-based page. Pair it with `onPageChange`. |
| `defaultPage` | `number` | `1` | Initial page when uncontrolled. Default 1. |
| `onPageChange` | `((page: number) => void)` |  |  |
| `pageSize` | `number` |  | Controlled rows per page. Pair it with `onPageSizeChange`. |
| `defaultPageSize` | `number` |  | Initial rows per page when uncontrolled. Default: the first of `pageSizeOptions`. |
| `onPageSizeChange` | `((pageSize: number) => void)` |  |  |
| `pageSizeOptions` | `readonly number[]` |  | Choices of the page size picker. Default `[10, 25, 50, 100]`; a single option hides the picker. |
| `labels` | `Partial<PaginationLabels>` |  | Texts (localized by default through `UiStrings`). |
| `variant` | `"default" \| "pages"` | `"default"` | `default`: rows per page, the range and first/previous/next/last icon buttons. `pages`: the range ("Showing 1–25 of 134") and Previous, page number and Next buttons; it shows the page size picker only when `pageSizeOptions` is passed with more than one option. |
| `hideOnSinglePage` | `boolean` | `variant === "pages"` | Renders nothing while every row fits on one page. Default `true` for `pages`, `false` otherwise. |

`*` marks a required prop.

It also accepts the native props of the element or primitive it renders (for example `className`, `id`, `aria-*` and event handlers).

## Storybook stories

- [Default](/storybook/?path=/story/containers-pagination--default)
- [Controlled](/storybook/?path=/story/containers-pagination--controlled)
- [Empty](/storybook/?path=/story/containers-pagination--empty)
- [Narrow](/storybook/?path=/story/containers-pagination--narrow)
- [Pages](/storybook/?path=/story/containers-pagination--pages)
- [Pages Spanish](/storybook/?path=/story/containers-pagination--pages-spanish)
- [Pages Single Page](/storybook/?path=/story/containers-pagination--pages-single-page)
- [Client Side](/storybook/?path=/story/containers-pagination--client-side)
- [Cursor](/storybook/?path=/story/containers-pagination--cursor)
- [Cursor Single Page](/storybook/?path=/story/containers-pagination--cursor-single-page)

## Source

`packages/ui/src/containers/pagination/pagination.tsx`