Pagination

A navigation component for paginating through large datasets with customizable page controls.

Anatomy

<script>
  import { Pagination } from "@saas-ui/svelte/components/pagination";
</script>

<Pagination
  count={100}
  pageSize={10}
  defaultPage={1}
/>

Examples

As Link Accessibility

Pagination as links for SEO-friendly navigation using type="link".

<Pagination
	count={20}
	pageSize={2}
	defaultPage={1}
	type="link"
	getHref={(page) => `?page=${page}`}
/>

Attached Accessibility

Pagination with visually attached buttons using the attached prop.

<Pagination
	count={10}
	pageSize={2}
	defaultPage={1}
	variant="solid"
	attached
/>

Basic Accessibility

Basic pagination with default styling and page numbers.

<Pagination count={100} pageSize={10} defaultPage={1} />

Colours Accessibility

Pagination with different colour schemes using the colour prop.

<Stack gap={4}>
	{#each colours as colour}
		<HStack align="center" gap={4}>
			<Text size="xs" class="min-w-[8ch] capitalize">{colour}</Text>
			<Pagination
				count={50}
				pageSize={10}
				defaultPage={1}
				variant="solid"
				{colour}
				aria-label="{colour} colour pagination"
			/>
		</HStack>
	{/each}
</Stack>

Compact Accessibility

Compact pagination showing page text only instead of individual page buttons.

<Pagination count={20} pageSize={2} defaultPage={1} compact />

Controlled Accessibility

Controlled pagination with external state management using the page prop.

<Pagination
	count={100}
	pageSize={10}
	page={controlledPage}
	onPageChange={(e) => (controlledPage = e.page)}
/>

Count Text Accessibility

Pagination with long count text format showing item range and total.

<Pagination
	count={50}
	pageSize={5}
	defaultPage={1}
	pageTextFormat="long"
	class="max-w-60"
/>

Data Driven Accessibility

Pagination integrated with data-driven content to display paginated items.

<Stack gap={4}>
	<Stack gap={2}>
		{#each visibleItems() as item}
			<Text>{item}</Text>
		{/each}
	</Stack>
	<Pagination
		page={dataDrivenPage}
		count={items.length}
		pageSize={dataPageSize}
		onPageChange={(e) => (dataDrivenPage = e.page)}
	/>
</Stack>

Sibling Count Accessibility

Pagination with more sibling pages visible using the siblingCount prop.

<Pagination count={200} pageSize={10} defaultPage={10} siblingCount={2} />

Sizes Accessibility

Pagination in different sizes. Available sizes: xs, sm, md, lg.

<Stack gap={8}>
	{#each paginationSizes as size}
		<HStack align="center" gap={4}>
			<Text size="xs" class="min-w-[3ch]">{size}</Text>
			<Pagination
				count={50}
				pageSize={10}
				defaultPage={1}
				{size}
				aria-label="{size} size pagination"
			/>
		</HStack>
	{/each}
</Stack>

Variants Accessibility

Pagination with different variants. Available variants: ghost, outline, solid.

<Stack gap={8}>
	{#each paginationVariants as variant}
		<HStack align="center" gap={4}>
			<Text size="xs" class="min-w-[8ch] capitalize">{variant}</Text>
			<Pagination
				count={100}
				pageSize={10}
				defaultPage={1}
				{variant}
				aria-label="{variant} variant pagination"
			/>
		</HStack>
	{/each}
</Stack>

Props

Pagination

A navigation component for paginating through data.

Prop	Type	Default	Description
`count`	`number`	-	Total number of data items.
`pageSize`	`number`	`10`	Number of data items per page.
`page`	`number`	-	The controlled active page.
`defaultPage`	`number`	`1`	The initial active page when uncontrolled.
`siblingCount`	`number`	`1`	Number of pages to show beside active page.
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	The size of the pagination items.
`variant`	`"ghost" \| "outline" \| "solid"`	`"ghost"`	The visual style variant of the pagination.
`colour`	`ColourName`	`"gray"`	The colour theme of the pagination.
`compact`	`boolean`	`false`	Whether to show compact page text instead of page items.
`pageTextFormat`	`"short" \| "long"`	`"short"`	The format of the page text when compact is true. "short" shows "1 of 7", "long" shows "1 - 5 of 50".
`attached`	`boolean`	`false`	Whether items should be visually attached.
`type`	`"button" \| "link"`	`"button"`	The type of the trigger element.
`getHref`	`(page: number) => string`	-	Function to generate href attributes for pagination links. Only used when type is 'link'.
`onPageChange`	`(details: { page: number }) => void`	-	Called when the page number changes.
`class`	`string`	-	Additional CSS classes to apply.
`style`	`string`	-	Inline styles.
`id`	`string`	-	The id of the pagination element.
`aria-label`	`string`	`"pagination"`	Accessible label for the pagination navigation. Required when multiple paginations exist on a page.