# Pagination (/docs/pagination)
## API Reference [#api-reference]
## Basic [#basic]
{`
import { Pagination } from "moduix";
export function PaginationDemo() {
return ;
}
`}
{(context) => }
{(context) => }
## Anatomy [#anatomy]
`Pagination` is built on top of `Toolbar` and renders page controls as focusable toolbar items.
It can include arrow controls, page number controls, and non-interactive ellipsis markers.
```text
Pagination
└─ Toolbar
├─ previous control (optional)
├─ page controls (optional)
├─ ellipsis markers (when range is collapsed)
└─ next control (optional)
```
```tsx
```
| Part | Role |
| ------------------ | --------------------------------------------------------------------------------- |
| `Pagination` | Root navigation region. Controls current page, range logic, variants, and sizing. |
| `previous` control | Moves to the previous page when arrows are enabled. |
| `page` controls | Select a specific page and expose the current page with `aria-current="page"`. |
| `ellipsis` marker | Indicates hidden pages when the full range is collapsed into the middle window. |
| `next` control | Moves to the next page when arrows are enabled. |
The component has no portal/backdrop service slots. Style it directly with `className` and CSS variables.
## Composition [#composition]
Use uncontrolled mode with `defaultPage` for local state. Use controlled mode with `page` and
`onPageChange` when pagination must stay in sync with URL state or external filters.
Use `getPageHref` to map pages to links for any URL scheme, such as `/page/7` or `?page=7`.
Use `showArrows` and `showPages` to keep only the controls you need for the layout.
## Examples [#examples]
### Numbers Only [#numbers-only]
Hide arrow controls when only direct page selection is needed.
{`
import { Pagination } from "moduix";
export function PaginationNumbersOnlyDemo() {
return ;
}
`}
### Arrows Only [#arrows-only]
Hide page numbers when the UI needs compact previous/next controls.
{`
import { Pagination } from "moduix";
export function PaginationArrowsOnlyDemo() {
return ;
}
`}
### Controlled With Links [#controlled-with-links]
Control the page from React state and provide link URLs for navigation and SEO-friendly anchors.
{`
import { Pagination } from "moduix";
import { useState } from "react";
export function PaginationControlledLinksDemo() {
const [page, setPage] = useState(5);
return (
\`?page=\${next}\`}
/>
);
}
`}
### Variants [#variants]
Use toolbar variants to match the surrounding surface.
{`
import { Pagination } from "moduix";
export function PaginationVariantsDemo() {
return (
<>
);
}
`}
### Sizes [#sizes]
Use `size` to fit compact and spacious interfaces.
{`
import { Pagination } from "moduix";
export function PaginationSizesDemo() {
return (
<>
);
}
`}
### Class Name [#class-name]
Use `className` to theme active items and container spacing with scoped CSS variables.
{`
import { Pagination } from "moduix";
export function PaginationClassNameDemo() {
return (
);
}
`}
{`
.customPagination {
--pagination-toolbar-padding-filled: var(--spacing-1);
--pagination-item-radius: var(--radius-sm);
--pagination-item-bg-active: var(--color-primary);
--pagination-item-color-active: var(--color-primary-foreground);
--pagination-item-border-color-active: var(--color-primary);
}
`}