Pagination

The <nys-pagination> provides users with the ability to to navigate through a large set of content or data that has been divided into smaller, more manageable sections or "pages."

Options

Small Screens

The <nys-pagination> component automatically renders in a condensed format on small screens.

Note: If totalPages is 1 then the <nys-pagination> component will not be visible.

Current Page

The prop currentPage takes in the page number you are currently on. This value cannot be larger than the value of totalPages. If a value larger than totalPages is passed in, it will return the last available page. The default value is 1.

Total Pages

The prop totalPages takes in the number of total pages to view.

Usage

When to use this component

• When displaying large data sets or search results that would be overwhelming to display all at once
• When users need control and orientation to navigate to a specific part of the content, such as page 5 of search results
• When performance and load times matter, since pagination lets you fetch and render smaller chunks of data instead of everything at once.

When to consider something else

• If the collection is shorter than 3–4 screen lengths, it’s better to display all items at once rather than using pagination.
• When you need to show progress through a series of tasks that must be completed in order—such as an onboarding process—use the <nys-stepper> component.

Accessibility

The <nys-pagination> component includes the following accessibility-focused features:

• Fewer buttons on a pagination interface are preferable because they minimize cognitive load, reduce visual clutter, and improve usability, especially on smaller screens. A simpler design helps users focus on the content and prevents analysis paralysis. Larger paginations use more space without proportional increases to the component’s functionality.
• Provide a clear, visible focus indicator for buttons so users can see where they are.
• Keyboard navigation support, allowing users to toggle the pages using the keyboard.
• Visual focus indicators to help users navigate the component.

Properties

CSS Variables

Events

The <nys-pagination> component emits one custom Javascript event:

1. nys-change – Fired when the currentPage value is changed.

Event details

The nys-change event includes a detail object with the following properties:

• id (string): The id of the pagination component.
• page (integer): The new value of currentPage

You can listen to these events using JavaScript:

// Select the pagination component
const pagination = document.querySelector("nys-pagination");
// Listen for the 'nys-change' event
pagination.addEventListener("nys-change", (event) => {
	console.log("Pagination is changed to page ${event.detail.page}");
});