---
title: Pagination
description: Page navigation component with configurable sibling count and edge display.
sidebar:
  order: 4
search:
  tags: [pages, previous, next, navigation]
---

# Pagination

> Page navigation component with configurable sibling count and edge display.

## Import

```tsx
import { Pagination } from 'moraine'
```

## Slot Structure

Page controls with previous, next, and numbered page link buttons.

```text
root
└── list
    ├── item (prev)
    │   └── prev (Button)
    ├── item (×n, page links)
    │   └── link (Button)
    └── item (next)
        └── next (Button)
```

## Examples

### Variants

Render controls as links and override variant pairing when needed.

```tsx
function Variants() {
  return (
    <Pagination
      total={60}
      itemsPerPage={10}
      to={(nextPage) => `#pagination&page=${nextPage}`}
      variant="outline"
      activeVariant="default"
      controlVariant="secondary"
    />
  )
}
```

### Sizes

Size scale from `xs` to `xl` for page links and previous/next controls.

```tsx
function Sizes() {
  const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const

  return (
    <div class="space-y-4">
      <For each={SIZES}>
        {(size) => (
          <div class="space-y-1">
            <p class="text-xs text-muted-foreground font-mono">{size}</p>
            <Pagination
              size={size}
              total={120}
              itemsPerPage={10}
              siblingCount={1}
              prevText="Prev"
              nextText="Next"
            />
          </div>
        )}
      </For>
    </div>
  )
}
```

### Controlled

Default ghost + outline controls with external page state management.

```tsx
function Controlled() {
  const [page, setPage] = createSignal(3)

  return (
    <div class="space-y-3">
      <Pagination
        page={page()}
        onPageChange={setPage}
        total={120}
        itemsPerPage={10}
        siblingCount={1}
        prevText="Previous"
        nextText="Next"
      />
      <p class="text-xs text-muted-foreground">Current page: {page()}</p>
    </div>
  )
}
```

### Minimal

Hide prev/next controls and show only page buttons.

```tsx
function Minimal() {
  return <Pagination total={80} itemsPerPage={10} showControls={false} />
}
```

## API Reference

### Attributes

#### `root`

Navigation container for page controls.

##### Data Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| data-orientation | string \| undefined | Stores the rendered orientation. |
| data-size | string | Stores the resolved size variant. |
| data-variant | string | Stores the resolved visual variant. |

##### ARIA Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| aria-label | boolean \| string \| undefined | Provides an accessible label when visible text is not sufficient. |
| role | string | Defines the semantic role exposed to assistive technology. |

#### `list`

Wrapper that lays out page, ellipsis, previous, and next controls.

#### `item`

Individual page control or ellipsis item.

##### ARIA Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| aria-hidden | boolean \| string \| undefined | Hides decorative content from assistive technology. |

#### `link`

Clickable page navigation control.

##### Data Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| data-current | string \| undefined | Present when the item represents the current location. |

##### ARIA Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| aria-current | string | Marks the current item in a set or navigation trail. |
| aria-label | boolean \| string \| undefined | Provides an accessible label when visible text is not sufficient. |

#### `prev`

Control that navigates to the previous page.

##### ARIA Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| aria-label | boolean \| string \| undefined | Provides an accessible label when visible text is not sufficient. |

#### `next`

Control that navigates to the next page.

##### ARIA Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| aria-label | boolean \| string \| undefined | Provides an accessible label when visible text is not sufficient. |

#### `ellipsis`

Non-interactive marker for skipped page ranges.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| activeVariant | "link" \| "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| undefined | outline | Visual variant for the active page button. |
| class | ClassValue | — | Class applied to the component root or trigger element. |
| classes | PaginationT.Classes \| undefined | — | Slot-based class overrides. |
| controlVariant | "link" \| "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| undefined | ghost | Visual variant for the previous/next control buttons. |
| defaultPage | number \| undefined | 1 | Initial page number when uncontrolled. |
| disabled | boolean \| undefined | — | Whether the pagination is disabled. |
| ellipsisIcon | IconT.Name | icon-ellipsis | Icon name for the ellipsis indicator. |
| itemsPerPage | number \| undefined | 10 | Number of items to display per page. |
| nextIcon | IconT.Name | icon-chevron-right | Icon name for the next button. |
| nextText | string \| undefined | — | Text to display in the next button. |
| onPageChange | ((page: number) => void) \| undefined | — | Callback triggered when the page changes. |
| page | number \| undefined | — | Controlled current page number (1-indexed). |
| prevIcon | IconT.Name | icon-chevron-left | Icon name for the previous button. |
| prevText | string \| undefined | — | Text to display in the previous button. |
| ref | JSX.HTMLElementTags["nav"] extends { ref?: infer Ref; } ? Ref : never \| undefined | — | — |
| showControls | boolean \| undefined | true | Whether to show previous and next control buttons. |
| siblingCount | number \| undefined | 2 | Number of page buttons to show on either side of the current page. |
| size | FormFieldSize \| undefined | md | Size of the pagination buttons. |
| style | JSX.CSSProperties \| undefined | — | — |
| styles | PaginationT.Styles \| undefined | — | Slot-based style overrides. |
| to | ((page: number) => string \| undefined) \| undefined | — | Function to generate a destination URL for a given page number.<br>If provided, pagination items will render as anchor tags. |
| total | number \| undefined | 0 | Total number of items across all pages. |
| variant | "link" \| "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| undefined | ghost | Visual variant for the page buttons. |

### ARIA

Accessibility attributes and roles emitted by the component markup.

| Attribute | Type | Description |
| --- | --- | --- |
| aria-atomic | boolean \| string \| undefined | Accessibility attribute forwarded by the rendered component. |
| aria-busy | boolean \| string \| undefined | Accessibility attribute forwarded by the rendered component. |
| aria-current | string | Marks the current item in a set or navigation trail. |
| aria-disabled | boolean \| string \| undefined | Indicates that the control is disabled. |
| aria-hidden | boolean \| string \| undefined | Hides decorative content from assistive technology. |
| aria-label | boolean \| string \| undefined | Provides an accessible label when visible text is not sufficient. |
| aria-live | string | Announces dynamic status changes to assistive technology. |
| role | string | Defines the semantic role exposed to assistive technology. |

### Data Attributes

State and slot attributes exposed for styling hooks and selectors.

| Attribute | Type | Description |
| --- | --- | --- |
| data-current | string \| undefined | Present when the item represents the current location. |
| data-disabled | string \| undefined | Present when the component or item is disabled. |
| data-loading | string \| undefined | Present when the component is loading. |
| data-orientation | string \| undefined | Stores the rendered orientation. |
| data-size | string | Stores the resolved size variant. |
| data-slot | string | Identifies the rendered slot for styling hooks and selectors. |
| data-variant | string | Stores the resolved visual variant. |