Navigation
Pagination
Splits a long list, such as invoices or backups, into pages. Page numbers are round pill buttons; the current page is filled ink.
import * as Pagination from '@statix/ui/pagination';Playground
<Pagination.Root count={120} perPage={10} bind:page>
{#snippet children({ pages, currentPage })}
<Pagination.Content>
<Pagination.Item><Pagination.Previous /></Pagination.Item>
{#each pages as p (p.key)}
<Pagination.Item>
{#if p.type === 'ellipsis'}
<Pagination.Ellipsis />
{:else}
<Pagination.Link page={p} isActive={currentPage === p.value} />
{/if}
</Pagination.Item>
{/each}
<Pagination.Item><Pagination.Next /></Pagination.Item>
</Pagination.Content>
{/snippet}
</Pagination.Root>Examples
Invoices
Bind page to slice your data. Pagination.Root computes the page list, including ellipses, and hands it to the children snippet.
- RE-2026-0420 19,00 €
- RE-2026-0419 31,00 €
- RE-2026-0418 43,00 €
- RE-2026-0417 19,00 €
- RE-2026-0416 31,00 €
<script lang="ts">
import * as Pagination from '@statix/ui/pagination';
const perPage = 5;
const invoices = Array.from({ length: 42 }, (_, i) => ({
number: `RE-2026-${String(420 - i).padStart(4, '0')}`,
amount: `${(19 + (i % 3) * 12).toFixed(2).replace('.', ',')} €`
}));
let page = $state(1);
const visible = $derived(invoices.slice((page - 1) * perPage, page * perPage));
</script>
<div class="flex w-full max-w-xl flex-col gap-4">
<ul class="divide-y divide-border rounded-lg bg-card px-5">
{#each visible as invoice (invoice.number)}
<li class="flex justify-between py-3 text-body">
<span class="text-ink">{invoice.number}</span>
<span class="text-ink-2 tabular-nums">{invoice.amount}</span>
</li>
{/each}
</ul>
<Pagination.Root count={invoices.length} {perPage} bind:page>
{#snippet children({ pages, currentPage })}
<Pagination.Content>
<Pagination.Item>
<Pagination.Previous />
</Pagination.Item>
{#each pages as p (p.key)}
<Pagination.Item>
{#if p.type === 'ellipsis'}
<Pagination.Ellipsis />
{:else}
<Pagination.Link page={p} isActive={currentPage === p.value} />
{/if}
</Pagination.Item>
{/each}
<Pagination.Item>
<Pagination.Next />
</Pagination.Item>
</Pagination.Content>
{/snippet}
</Pagination.Root>
</div>Previous and next only
For lists where the page number does not matter. The range from the snippet tells the customer where they are.
<script lang="ts">
import * as Pagination from '@statix/ui/pagination';
let page = $state(2);
</script>
<Pagination.Root count={64} perPage={10} bind:page>
{#snippet children({ range })}
<Pagination.Content class="gap-3">
<Pagination.Item>
<Pagination.Previous />
</Pagination.Item>
<Pagination.Item class="text-small text-muted-foreground tabular-nums">
Backups {range.start} to {range.end} of 64
</Pagination.Item>
<Pagination.Item>
<Pagination.Next />
</Pagination.Item>
</Pagination.Content>
{/snippet}
</Pagination.Root>Small
Pass size="icon-sm" to Pagination.Link for 36px buttons in dense tables.
<script lang="ts">
import * as Pagination from '@statix/ui/pagination';
</script>
<Pagination.Root count={240} perPage={20} page={4}>
{#snippet children({ pages, currentPage })}
<Pagination.Content>
{#each pages as p (p.key)}
<Pagination.Item>
{#if p.type === 'ellipsis'}
<Pagination.Ellipsis class="size-control-sm" />
{:else}
<Pagination.Link page={p} size="icon-sm" isActive={currentPage === p.value} />
{/if}
</Pagination.Item>
{/each}
</Pagination.Content>
{/snippet}
</Pagination.Root>Guidelines
Do
- Put pagination directly under the list it controls.
- Keep the page size steady. Ten to twenty rows works for invoices.
- Show the total ("Backups 11 to 20 of 64") when the count helps.
Don't
- Do not paginate lists under one page. Show everything.
- Do not use pagination for a feed the customer reads top to bottom. Load more instead.
Accessibility
- Pagination.Root renders a <nav aria-label="Pagination">.
- Page buttons are labelled "Page 3" and the current one has aria-current="page".
- Previous and Next are labelled "Go to previous page" and "Go to next page" and are disabled at the ends.
- Left and Right arrows move focus between the buttons.
API reference
Pagination.Root
renders<nav> and accepts its attributes| Prop | Type | Default |
|---|---|---|
count * | number Total number of items. | – |
perPage | number Items per page. | 10 |
page bind | number The current page, starting at 1. | 1 |
siblingCount | number Page numbers shown on each side of the current one. | 1 |
onPageChange | (page: number) => void Called when the page changes. | – |
loop | boolean Arrow keys wrap around. | false |
children | Snippet<[{ pages, range, currentPage }]> Receives the page list (pages and ellipses) and the visible item range. | – |
ref bind | HTMLElement | null The nav element. | – |
class | ClassValue Merged with the root classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="pagination" | Always present. |
Pagination.Content
renders<ul> and accepts its attributes| Prop | Type | Default |
|---|---|---|
class | ClassValue Merged with the list classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="pagination-content" | Always present. |
Pagination.Item
renders<li> and accepts its attributes| Prop | Type | Default |
|---|---|---|
class | ClassValue Classes for the list item. | – |
| Data attribute | Meaning |
|---|---|
data-slot="pagination-item" | Always present. |
Pagination.Link
renders<button> and accepts its attributesA page number. Ghost when inactive, ink fill when active.
| Prop | Type | Default |
|---|---|---|
page * | PageItem The page from the children snippet. | – |
isActive * | boolean Marks the current page. | – |
size | 'icon-sm' | 'icon' | 'icon-lg' | ButtonSize Button size: 36, 44 or 52px. | 'icon' |
class | ClassValue Merged with the button classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="pagination-link" | Always present. |
data-active | "true" on the current page. |
data-size | The size. |
Pagination.Previous / Pagination.Next
renders<button> and accepts its attributesGhost pill buttons with a chevron. The label hides below 640px.
| Prop | Type | Default |
|---|---|---|
class | ClassValue Merged with the button classes. | – |
Pagination.Ellipsis
renders<span> and accepts its attributesMarks skipped pages. Hidden from screen readers except for a "More pages" label.
| Prop | Type | Default |
|---|---|---|
class | ClassValue Merged with the ellipsis classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="pagination-ellipsis" | Always present. |
Pagination.PrevButton / Pagination.NextButton
Older shadcn-svelte names. They accept children to replace the label. Prefer Previous and Next.