---
title: Pagination
description: Navigate a result set by page using state or destinations.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Pagination

> Navigate a result set by page using state or destinations.

## Anatomy

```text
Pagination [component; slot=root; <nav>]
├── list [slot]
│   ├── listItem [slot]
│   │   └── prev [slot]
│   ├── listItem [slot]
│   │   └── item [slot]
│   └── listItem [slot]
│       └── next [slot]
└── status [internal]
```

## Usage

Use Pagination when a result set has a known page count. The application owns data fetching and the
mapping from page numbers to URLs or controlled state. Do not use Pagination for a wizard; use
[Stepper](https://moraine.subf.dev/components/stepper.md) for a fixed sequence of steps.

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

export function Example() {
  return <Pagination total={100} pageSize={10} defaultPage={1} />
}
```

### Current page

Use `page` with `onPageChange` for controlled navigation, or `defaultPage` to start uncontrolled.
`total` is the number of records, not the page count; the component derives the page count,
`ceil(total / pageSize)`, from `pageSize`. The page count is at least 1. A page outside that range
is clamped for display, so reset the page when `pageSize` changes. `onPageChange` also fires in
controlled mode, so write the value back to `page`.

```tsx
<Pagination total={100} pageSize={10} page={page()} onPageChange={setPage} />
```

### Page window and controls

`siblingCount` (default `2`) sets how many page numbers show on each side of the current page. The
first and last pages always show, with ellipses for skipped ranges. Every page shows without
ellipses when `2 * siblingCount + 5` reaches the page count. Set `controls={false}` to hide Previous
and Next. `prevText` and `nextText` add visible text to those controls; their accessible names still
come from `translations`.

```tsx
<Pagination total={500} pageSize={10} siblingCount={1} prevText="Previous" nextText="Next" />
```

### Rendering links

Use `getPageHref(page)` by itself to render page controls as anchors. The current page stays a button.
For router integration, use `itemRender` for numbered items and `controlRender` for Previous/Next; these
props are independent and `getPageHref` still only generates the destination. Clicking a link also calls
`onPageChange`. Previous on the first page and Next on the last page remain disabled buttons even
when `controlRender` is set, and `disabled` turns every control into a disabled button.

`itemRender` and `controlRender` take a component that receives native anchor props
(`PaginationT.ItemRenderProps`); spread them onto your router link. The current page has no
`href`, so handle that case in the component.

```tsx
<Pagination
  itemRender={RouterLink}
  controlRender={RouterLink}
  total={50}
  pageSize={10}
  page={page()}
  getPageHref={(page) => `/results?page=${page}`}
/>
```

### Keyboard interaction

Pagination adds no arrow-key navigation across controls. Each page control keeps the keyboard
semantics of the button or link it renders. A visually hidden live region announces the current
page after each change.

## Examples

### Browse a result set

Drive the current page from local state and show which page is active.

```tsx
import { Pagination } from 'moraine'
import { createSignal } from 'solid-js'

export function PageState() {
  const [page, setPage] = createSignal(1)

  return (
    <div class="flex flex-col gap-3 items-center">
      <Pagination total={100} pageSize={10} page={page()} onPageChange={setPage} />
      <p class="text-xs text-muted-foreground">
        Active page: <span class="text-foreground font-medium">{page()}</span> of 10
      </p>
    </div>
  )
}
```

### Keep the page in the URL

Render numbered items and Previous/Next through Solid Router. Destinations such as
`/pagination?page=2` stay in sync with the current page.

```tsx
import { A, useSearchParams } from '@solidjs/router'
import { Pagination } from 'moraine'
import type { PaginationT } from 'moraine'
import { Show, createMemo } from 'solid-js'

// The current page has no destination, so it keeps a plain anchor instead of a router link.
function RouterLink(props: PaginationT.ItemRenderProps) {
  return (
    <Show when={props.href} fallback={<a {...props} />}>
      {(href) => <A {...props} href={href()} />}
    </Show>
  )
}

export function LinkRendering() {
  const [params] = useSearchParams()
  const page = createMemo(() => {
    const requested = Number(params.page)
    return Number.isFinite(requested) ? Math.min(5, Math.max(1, Math.trunc(requested))) : 1
  })
  return (
    <div class="flex w-full justify-center">
      <Pagination
        itemRender={RouterLink}
        controlRender={RouterLink}
        total={50}
        pageSize={10}
        page={page()}
        siblingCount={1}
        getPageHref={(page) => `/pagination?page=${page}`}
      />
    </div>
  )
}
```

### Page a customer table

Slice the visible rows from application state. Previous and Next stay labeled.

```tsx
import { Badge, Pagination } from 'moraine'
import { createMemo, createSignal, For } from 'solid-js'

export function Controlled() {
  const [page, setPage] = createSignal(1)
  const pageSize = 3

  const ALL_CUSTOMERS = [
    { id: 1, name: 'Stripe Inc.', plan: 'Enterprise', status: 'Active', mrr: '$2,400' },
    { id: 2, name: 'Vercel Labs', plan: 'Enterprise', status: 'Active', mrr: '$1,800' },
    { id: 3, name: 'Linear App', plan: 'Pro', status: 'Active', mrr: '$450' },
    { id: 4, name: 'Supabase Inc.', plan: 'Enterprise', status: 'Active', mrr: '$3,200' },
    { id: 5, name: 'Resend Co.', plan: 'Pro', status: 'Active', mrr: '$600' },
    { id: 6, name: 'Raycast HQ', plan: 'Pro', status: 'Trial', mrr: '$0' },
    { id: 7, name: 'Figma Design', plan: 'Enterprise', status: 'Active', mrr: '$4,500' },
    { id: 8, name: 'Midjourney AI', plan: 'Enterprise', status: 'Active', mrr: '$6,000' },
  ]

  const currentRecords = createMemo(() => {
    const start = (page() - 1) * pageSize
    return ALL_CUSTOMERS.slice(start, start + pageSize)
  })

  return (
    <div class="p-4 b-1 b-border rounded-xl bg-card max-w-xl space-y-4">
      <div class="flex items-center justify-between">
        <h4 class="text-sm font-semibold">Active Customers</h4>
        <span class="text-xs text-muted-foreground">
          Showing {(page() - 1) * pageSize + 1}–{Math.min(page() * pageSize, ALL_CUSTOMERS.length)}{' '}
          of {ALL_CUSTOMERS.length} records
        </span>
      </div>

      <div class="text-xs divide-border divide-y">
        <For each={currentRecords()}>
          {(customer) => (
            <div class="py-2.5 flex items-center justify-between">
              <div>
                <p class="text-foreground font-medium">{customer.name}</p>
                <p class="text-muted-foreground">{customer.plan} tier</p>
              </div>
              <div class="flex gap-3 items-center">
                <Badge variant={customer.status === 'Active' ? 'solid' : 'outline'} size="sm">
                  {customer.status}
                </Badge>
                <span class="font-medium font-mono">{customer.mrr}/mo</span>
              </div>
            </div>
          )}
        </For>
      </div>

      <div class="pt-2 border-t border-border flex justify-center">
        <Pagination
          page={page()}
          onPageChange={setPage}
          total={ALL_CUSTOMERS.length}
          pageSize={pageSize}
          siblingCount={1}
          prevText="Previous"
          nextText="Next"
        />
      </div>
    </div>
  )
}
```

### Change results per page

Reset to page 1 when the page size changes so the requested page stays inside the new count.

```tsx
import { Field, Pagination, Select } from 'moraine'
import type { SelectT } from 'moraine'
import { createMemo, createSignal, For } from 'solid-js'

const RESULTS = [
  'Account settings',
  'Billing history',
  'Connected apps',
  'Developer keys',
  'Email preferences',
  'Export requests',
  'Member invitations',
  'Notification rules',
  'Privacy controls',
  'Team permissions',
  'Usage reports',
  'Workspace details',
]

const PAGE_SIZES: SelectT.Item<number>[] = [
  { value: 3, label: '3 results' },
  { value: 6, label: '6 results' },
  { value: 12, label: '12 results' },
]

export function PageSize() {
  const [page, setPage] = createSignal(1)
  const [pageSize, setPageSize] = createSignal(3)
  const visible = createMemo(() => {
    const start = (page() - 1) * pageSize()
    return RESULTS.slice(start, start + pageSize())
  })

  return (
    <div class="max-w-md w-full space-y-4">
      <Field label="Results per page">
        <Select
          items={PAGE_SIZES}
          value={pageSize()}
          onValueChange={(value) => {
            if (value === null) {
              return
            }
            setPageSize(value)
            setPage(1)
          }}
        />
      </Field>
      <ul class="text-sm border-y border-border divide-border divide-y">
        <For each={visible()}>{(result) => <li class="py-2">{result}</li>}</For>
      </ul>
      <Pagination
        total={RESULTS.length}
        pageSize={pageSize()}
        page={page()}
        onPageChange={setPage}
      />
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `pagination-item`, `pagination-prev`, `pagination-next` | Present when the component, slot, or item is disabled. |
| `data-loading` | `pagination-item`, `pagination-prev`, `pagination-next` | Present when the component or async operation is loading. |
| `data-text` | `pagination-prev`, `pagination-next` | Present when the input group part contains text. |
| `data-current` | `pagination-item` | Present when the item represents the current location or step. |
| `data-ellipsis` | `pagination-ellipsis` | — |

### Props

Props for the Pagination component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| activeVariant | 'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'link' \| undefined | 'outline' | Visual variant for the active page button. |
| controlRender | Component<ControlRenderProps> \| undefined | — | Component that renders the previous and next controls, like `itemRender` for page items. It<br>receives `href` and `rel` (`prev` or `next`) when `getPageHref` returns a URL. Controls at an<br>edge and all controls while `disabled` stay disabled buttons. |
| controls | boolean \| undefined | true | Whether to show previous and next control buttons. |
| controlVariant | 'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'link' \| undefined | 'ghost' | Visual variant for the previous/next control buttons. |
| defaultPage | number \| undefined | 1 | Initial page number when uncontrolled. Ignored when `page` is set. |
| disabled | boolean \| undefined | false | Disables every page item and control; they render as disabled buttons without links. |
| ellipsisIcon | IconT.Name \| undefined | 'icon-ellipsis' | Icon name for the ellipsis indicator. |
| getPageHref | ((page: number) => string \| undefined) \| undefined | — | Builds the destination URL for a page number. It is called with the target page of each<br>numbered item other than the current page, and of the previous and next controls. An item<br>that gets a URL renders as `<a href>` (or through `itemRender` / `controlRender` when set) and still calls<br>`onPageChange` on click; returning `undefined` keeps a plain button. It is ignored while<br>`disabled`, and previous on the first page and next on the last page stay disabled buttons. |
| itemRender | Component<ItemRenderProps> \| undefined | — | Component that renders every numbered page item in place of the default element, for example<br>a router link. It is mounted as a component and receives the item's native anchor props,<br>including `href` when `getPageHref` returns a URL, plus `class`, `children`, and handlers;<br>spread them onto the rendered element. By default an item renders as `<a>` when it has a URL<br>and as a `button` otherwise. Ignored while `disabled`. |
| nextIcon | IconT.Name \| undefined | 'icon-chevron-right' | Icon name for the next button. |
| nextText | string \| undefined | — | Text shown in the next button. When set, the control shows the text with `nextIcon` after it<br>instead of an icon-only button. Its accessible name still comes from `translations.next`,<br>not from this text. |
| onPageChange | ((page: number) => void) \| undefined | — | Called with the new page number when the user selects a different page through a numbered<br>item or the previous and next controls. It does not fire for the current page or while<br>`disabled`, and it fires in controlled mode too, so a controlled pagination must write the<br>value back to `page`. |
| page | number \| undefined | — | Controlled current page number (1-indexed). While `undefined` the page is uncontrolled and<br>follows `defaultPage`. Non-integers are truncated and the displayed page is clamped to the<br>valid range. |
| pageSize | number \| undefined | 10 | Number of items per page. Together with `total` it sets the page count,<br>`ceil(total / pageSize)`. Truncated to an integer of at least 1; invalid values fall back to<br>the default. |
| prevIcon | IconT.Name \| undefined | 'icon-chevron-left' | Icon name for the previous button. |
| prevText | string \| undefined | — | Text shown in the previous button. When set, the control shows the text with `prevIcon`<br>before it instead of an icon-only button. Its accessible name still comes from<br>`translations.prev`, not from this text. |
| ref | Ref<HTMLElement> \| undefined | — | Ref forwarded to the root `<nav>` element. |
| siblingCount | number \| undefined | 2 | Number of page buttons to show on either side of the current page.<br>Finite integer values are clamped between 0 and 100. When `2 * siblingCount + 5` is at least<br>the page count, every page is shown without ellipses. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Size of the pagination buttons. |
| tone | Tone \| undefined | 'neutral' | Color tone for pagination buttons. |
| total | number \| undefined | 0 | Total number of items (records) across all pages, not the number of pages. The page count is<br>at least 1, so `0` still renders a single page. |
| translations | Translations \| undefined | — | Overrides for the localized accessibility strings of this instance; omitted keys fall back to<br>the locale defaults. `label` is the `nav` label; `status`, `page` and `currentPage` receive<br>`{ page, total }`; `prev` and `next` receive `{ page }`, which is `undefined` when already at<br>that edge. |
| variant | 'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'link' \| undefined | 'ghost' | Visual variant for the page buttons. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`getPageHref` example**

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

<Pagination total={100} pageSize={10} getPageHref={(page) => `/posts?page=${page}`} />
```

**`itemRender` example**

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

const RouterLink = (props: PaginationT.ItemRenderProps) => <a {...props} />

<Pagination
  total={100}
  pageSize={10}
  getPageHref={(page) => `/posts?page=${page}`}
  itemRender={RouterLink}
/>
```

**`translations` example**

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

<Pagination
  total={100}
  translations={{
    label: 'Pages des résultats',
    status: ({ page, total }) => `Page ${page} sur ${total}`,
    prev: () => 'Page précédente',
    next: () => 'Page suivante',
  }}
/>
```
