# Pagination
> Pagination with previous and next buttons, page numbers and ellipses, where a pixel block slides to the page you pick.
- React: `import { PxPagination } from "@/components/lumesec/px-pagination"`
- Collection: Pixel UI (https://elements.lumesec.ai/components/pixel-ui)
- Registry item: https://elements.lumesec.ai/r/px-pagination.json
- Page: https://elements.lumesec.ai/components/pixel-ui/pagination



Live preview: https://elements.lumesec.ai/view/px-pagination

Demo source:

```tsx
import { PxPagination } from "@/components/lumesec/px-pagination";

export default function PxPaginationDemo() {
  return <PxPagination total={24} defaultPage={5} className="w-full max-w-[380px] justify-center" />;
}
```

## Playground

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

## Installation

```bash
npx shadcn@latest add @lumesec/px-pagination
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-pagination.json
```

## Usage

React:

```tsx
"use client";

import * as React from "react";

import { PxPagination } from "@/components/lumesec/px-pagination";

export function Example() {
  const [page, setPage] = React.useState(5);
  return <PxPagination total={24} page={page} onPageChange={setPage} />;
}
```

## Behaviour

Page buttons with ellipses, where the current-page block slides to the page you pick.

## API reference

### Props

Also accepts every prop of `<nav>` (`React.ComponentProps<"nav">`), spread onto the root element.

| Prop           | Type                     | Default | Description                                                                                    |
| -------------- | ------------------------ | ------- | ---------------------------------------------------------------------------------------------- |
| `page`         | `number`                 | —       | Controlled current page, from 1. Rounded and clamped to 1 to `total`. Use with `onPageChange`. |
| `defaultPage`  | `number`                 | `1`     | Initial page when uncontrolled.                                                                |
| `total`        | `number`                 | `24`    | Number of pages, at least 1.                                                                   |
| `onPageChange` | `(page: number) => void` | —       | Called when the user picks a page. Changing `page` from code does not call it.                 |

### Ref

`ref` points at the root `HTMLElement`.

## Accessibility

* The root is a `<nav>` with `aria-label="Pagination"` (pass `aria-label` to change it).
* Page buttons are native buttons labelled "Page N"; the current one has `aria-current="page"`.
* The previous and next buttons are labelled "Previous page" and "Next page" and are disabled at the ends.
* Ellipses are `aria-hidden`. After a pick, focus stays on the pressed button, so Next can be pressed repeatedly; when that button becomes disabled (Next on the last page), focus moves to the new current page.
* Reduced motion: the current-page block jumps instead of sliding.

## Theming

Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--lumesec`, `--lumesec-foreground`, `--foreground` and `--muted-foreground`.

## Notes

* Up to seven pages are all shown. Beyond that it shows the first and last page, a window around the current page and ellipses.
* It does not navigate or load data; handle `onPageChange`.