Skip to main content

Pagination

Navigate a result set by page using state or destinations.

Current Page: 1 of 10
Props
Slots

Anatomy#

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 for a fixed sequence of steps.

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.

<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.

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

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.

<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.

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.

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.

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.

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
data-disabled
Slot: pagination-itempagination-prevpagination-next
Description: Present when the component, slot, or item is disabled.
data-loading
Slot: pagination-itempagination-prevpagination-next
Description: Present when the component or async operation is loading.
data-text
Slot: pagination-prevpagination-next
Description: Present when the input group part contains text.
data-current
Slot: pagination-item
Description: Present when the item represents the current location or step.
data-ellipsis
Slot: pagination-ellipsis
Description: —

Props#

Props for the Pagination component. Renders a <nav> element by default.

Prop