Skip to content
Statix Design System

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

Controls
<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
PropTypeDefault
count * number

Total number of items.

–
perPage number

Items per page.

10
page bindnumber

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 bindHTMLElement | null

The nav element.

–
class ClassValue

Merged with the root classes.

–
Data attributeMeaning
data-slot="pagination"Always present.

Pagination.Content

renders <ul> and accepts its attributes
PropTypeDefault
class ClassValue

Merged with the list classes.

–
Data attributeMeaning
data-slot="pagination-content"Always present.

Pagination.Item

renders <li> and accepts its attributes
PropTypeDefault
class ClassValue

Classes for the list item.

–
Data attributeMeaning
data-slot="pagination-item"Always present.

Pagination.Link

renders <button> and accepts its attributes

A page number. Ghost when inactive, ink fill when active.

PropTypeDefault
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 attributeMeaning
data-slot="pagination-link"Always present.
data-active"true" on the current page.
data-sizeThe size.

Pagination.Previous / Pagination.Next

renders <button> and accepts its attributes

Ghost pill buttons with a chevron. The label hides below 640px.

PropTypeDefault
class ClassValue

Merged with the button classes.

–

Pagination.Ellipsis

renders <span> and accepts its attributes

Marks skipped pages. Hidden from screen readers except for a "More pages" label.

PropTypeDefault
class ClassValue

Merged with the ellipsis classes.

–
Data attributeMeaning
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.