Pagination

Example

<nav aria-label="Pagination" data-slean="pagination">
	<ul>
		<li><a href="?page=4" rel="prev" data-slean-part="previous">Previous</a></li>
		<li><a href="?page=1">1</a></li>
		<li data-slean-part="ellipsis" aria-hidden="true">…</li>
		<li><a href="?page=4">4</a></li>
		<li><a href="?page=5" aria-current="page">5</a></li>
		<li><a href="?page=6">6</a></li>
		<li data-slean-part="ellipsis" aria-hidden="true">…</li>
		<li><a href="?page=12">12</a></li>
		<li><a href="?page=6" rel="next" data-slean-part="next">Next</a></li>
	</ul>
</nav>

<!-- Pagination.svelte: <Pagination current={5} total={12} /> renders the HTML above. -->
<script lang="ts">
	import '@svelte-lean/styles/pagination.css';
	import { pageItems } from './pagination-items';

	let { current, total }: { current: number; total: number } = $props();
	const href = (page: number) => `?page=${page}`;
	// At an end, previous or next has no href: not a link, not focusable.
	const first = $derived(current <= 1);
	const last = $derived(current >= total);
</script>

<nav aria-label="Pagination" data-slean="pagination">
	<ul>
		<li>
			<a href={first ? undefined : href(current - 1)} rel={first ? undefined : 'prev'} data-slean-part="previous">Previous</a>
		</li>
		{#each pageItems(current, total) as item, i (item ?? `gap-${i}`)}
			{#if item === null}
				<li data-slean-part="ellipsis" aria-hidden="true">…</li>
			{:else}
				<li>
					<a href={href(item)} aria-current={item === current ? 'page' : undefined}>{item}</a>
				</li>
			{/if}
		{/each}
		<li>
			<a href={last ? undefined : href(current + 1)} rel={last ? undefined : 'next'} data-slean-part="next">Next</a>
		</li>
	</ul>
</nav>

Why this implementation exists

Pagination is navigation: every page of results has a URL a reader can open, share and come back to. Links in a named <nav> give that for free, with focus, Enter, history and a working page without JavaScript; aria-current="page" says which one is shown.

Svelte Lean ships the styles and the two decisions markup gets wrong: an end of the range is an <a> without href, which the browser takes out of the tab order, instead of a link that is only marked disabled; and the ellipsis is hidden from assistive technology.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/pagination.css';

Render one link per listed page with href, aria-current="page" on the current one, data-slean-part="previous" and "next" around them, and an aria-hidden ellipsis item where pages are skipped.

Read the page number from the URL and compute the items with a helper like the one below. A table that pages in place has its own pagination (see the table’s Pagination page).

Anatomy

Runtime profile

Tier 0: the pagination has no behavior module, the Vite plugin maps pagination to no module, and the page ships no Svelte Lean JavaScript for it. The example’s reading of the URL is page code, not a package runtime.

Accessibility contract

• A named <nav> landmark; aria-current="page" on the current page’s link.
• Previous and next have visible text; at an end they have no href, so they are not links and not focusable.
• Never aria-disabled="true" on a link that keeps its href: it would still be followed.
• The ellipsis is aria-hidden="true".

Keyboard

Platform features

Without JavaScript

Fully functional: each link loads its page. On this site the page is the same document with a different query string.

Server rendering

Render the links from the page number in the URL. Every link is a URL the server can render.

Before hydration

Nothing is attached. The links work before hydration; afterwards a client-side router may handle them without changing the markup.

Styling

pagination.css sizes each link to the small control height (which grows on a coarse pointer), gives the current page the soft accent, sets an end without href in the muted text color, sets the ellipsis in the muted text color and draws the previous and next chevrons with borders, mirrored under :dir(rtl). Under forced colors only the current page keeps a border. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :dir(rtl), :focus-visible, :hover, [aria-current="page"], [href].

Controlled integration

The application owns the page number, and the URL is its home. In SvelteKit, read it from page.url and pass it to the component above.

<script lang="ts">
	import { page } from '$app/state';
	import Pagination from './Pagination.svelte';

	// The application owns the page number; the URL is its home.
	const current = $derived(Number(page.url.searchParams.get('page')) || 1);
</script>

<Pagination {current} total={12} />

Compatibility notes

Links, <nav> and aria-current are widely available. The chevrons use the rotate property (Baseline 2022) and :dir() (Baseline 2023); the current page’s border uses color-mix() (Baseline 2023) and stays transparent without it.

Examples

First page

On the first page, previous has no href. An <a> without href is not a link: Tab skips it, a screen reader does not list it, and the stylesheet sets it in the muted text color while it keeps its place. On the last page the same holds for next.

<nav aria-label="Pagination" data-slean="pagination">
	<ul>
		<!-- No href: not a link, not focusable, muted. -->
		<li><a data-slean-part="previous">Previous</a></li>
		<li><a href="?page=1" aria-current="page">1</a></li>
		<li><a href="?page=2">2</a></li>
		<li><a href="?page=3">3</a></li>
		<li><a href="?page=2" rel="next" data-slean-part="next">Next</a></li>
	</ul>
</nav>

Page items

Which pages to list is the application’s decision. This helper, used by the example above, keeps the first and last page and one page on each side of the current one; it is not part of any package.

/**
 * The items of a pagination: page numbers around `current`, the first and the last page, and
 * `null` where pages are skipped. A gap of one page shows that page instead of an ellipsis.
 * An application helper for /primitives/pagination, shown on the page as source; it is not part
 * of any package.
 */
export function pageItems(current: number, total: number, around = 1): (number | null)[] {
	const pages = new Set([1, total]);
	for (let page = current - around; page <= current + around; page++) {
		if (page >= 1 && page <= total) pages.add(page);
	}
	const items: (number | null)[] = [];
	for (const page of [...pages].sort((a, b) => a - b)) {
		const last = items.at(-1);
		if (typeof last === 'number' && page - last === 2) items.push(last + 1);
		else if (typeof last === 'number' && page - last > 2) items.push(null);
		items.push(page);
	}
	return items;
}

Testing

• apps/playground/tests/primitives/feedback-navigation.spec.ts Playwright: roles, names and states in the accessibility tree, keyboard, RTL, reduced motion, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/pagination/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/pagination/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/pagination.css the optional stylesheet