lab components / Navigation

Pagination

Enable users to navigate efficiently through large datasets or content spanning multiple pages. Allow customization of the number of items displayed per page.

Examples Properties Guidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { Pagination } from "@siteimprove/fancylab";

#Examples

Pagination is a crucial navigation element for large datasets or lengthy content. It breaks information into manageable chunks, preventing overwhelm and improving the user experience.

Pagination is composed of

Total item count: Clearly show the range of currently visible items (e.g., "1-10 of 100").
Navigation controls:
- Previous/Next buttons: Use clear icons (e.g., chevrons) or text labels.
- First/Last buttons (optional): Include for large datasets to enable quick navigation.
- Page number information and input field (optional): Display the current page and allow direct input for specific pages (e.g., "Page 3 of 10").
Items per page (optional): Allow users to adjust the number of items displayed per page.

1 - 5 of 1000 items

CodeHTML output

const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(5);
const allData = Array.from(Array(1000).keys());
const pagedData = allData.slice((page - 1) * pageSize, page * pageSize);

return (
	<Pagination
		count={pagedData.length}
		total={allData.length}
		page={page}
		setPage={setPage}
		pageSize={pageSize}
		setPageSize={setPageSize}
		cancelLabel="Cancel"
		confirmLabel="Confirm"
		firstLabel="First"
		prevLabel="Previous"
		nextLabel="Next"
		lastLabel="Last"
		pagingInfoLabel={(startIdx: number, endIdx: number, total: number) =>
			`${startIdx} - ${endIdx} of ${total} items`
		}
		pageLabel="Page"
		pageXofYLabel={(current: number, total: number) => `Page ${current} of ${total}`}
		pageSizeSelectionLabel={(pageSize: number) => `${pageSize} items`}
		pageSizeSelectorPrefix="Show"
		pageSizeSelectorPostfix="per page"
		pageSizeLabel="Items per page"
		defaultError="Default pagination error"
		wholeNumberError="Must be a whole number"
		outOfBoundsError={(total: number) => `Enter a number between 1 and ${total}`}
		ariaLabel="Pagination"
	/>
);

#Properties

1 - 5 of 25 items

CodePropsHTML output

Property	Description	Defined	Value
totalRequired	`number`Total count of items	YesNo
pageRequired	`number`Selected page number	YesNo
setPageRequired	`function`Callback to change the selected page	YesNo
pageSizeRequired	`number`Selected page size	YesNo
setPageSizeRequired	`\| function`Callback to change the selected page size	YesNo
cancelLabelRequired	`string`Label for the cancel button	YesNo
confirmLabelRequired	`string`Label for the confirm button	YesNo
firstLabelRequired	`string`Tooltip text for the first button	YesNo
prevLabelRequired	`string`Tooltip text for the previous button	YesNo
nextLabelRequired	`string`Tooltip text for the next button	YesNo
lastLabelRequired	`string`Tooltip text for the last button	YesNo
pagingInfoLabelRequired	`function`Label for paging info - something like `${startIdx} - ${endIdx} of ${total} items`	YesNo
pageLabelRequired	`string`Label for page input	YesNo
pageXofYLabelRequired	`function`Label for page dropdown button - something like `Page ${current} of ${total}	YesNo
pageSizeSelectionLabelRequired	`function`Label for pageSize dropdown button - something like `${pageSize} items`	YesNo
pageSizeSelectorPrefixRequired	`string`Label before pageSize changer - Show (<- this part) DROPDOWN per page	YesNo
pageSizeSelectorPostfixRequired	`string`Label after pageSize changer - Show DROPDOWN per page (<- this part)	YesNo
pageSizeLabelRequired	`string`Label for pageSize radios - something like "Items per page"	YesNo
defaultErrorRequired	`string`Default error for page number input	YesNo
wholeNumberErrorRequired	`string`Error for page number input when number is not integer	YesNo
outOfBoundsErrorRequired	`function`Error for page number input when number is out of bounds (below 1 and above total)	YesNo
countOptional	`number`Count of items	YesNo
loadingOptional	`boolean`Loading state	YesNo	truefalse
observeKeyPrefixOptional	`string`Used as data observe key for pagination buttons	YesNo
ariaLabelOptional	`string`Text for the ARIA label	YesNo

The amount of information exceeds a single page's comfortable display capacity.
Users need to locate specific items within a larger collection.
You want to enhance the perceived loading speed of a page by breaking it into smaller chunks.

#Placement

Pagination is typically used in the following places:

Below content: The most common and intuitive location.
Within Data Tables/Lists: Enhance navigation within structured data.
Search results: Facilitate browsing through multiple pages of results.

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your Pagination to existing components for visual consistency.
Loading states: Use visual cues (e.g., Spinner) to indicate when pages are loading.
Empty states: Display a friendly message when no results are found on a page (e.g., "No results found for this page.").
Error states: If pagination fails, provide a clear error message (e.g Toast) and offer solutions (e.g., "An error occurred while loading this page. Please try again later.").
Items per page: Provide reasonable default options based on content type.