Pagination

The <nys-pagination> component provides Previous/Next buttons and numbered page links for navigating large sets of content or data. It auto-collapses page numbers with ellipses when there are many pages, and renders a compact layout on mobile.

Copy Code
<nys-pagination currentPage="2" totalPages="7"></nys-pagination>

Can't use NYS Design System web components in your project? Try using the CSS Variables instead.


Accessibility

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

  • Each page button includes an ariaLabel of "Page N" so screen readers announce the page number clearly.

  • Previous and Next buttons are disabled (not removed) when at the first or last page, so screen readers can still discover them and understand the navigation range.

  • On mobile, Previous and Next buttons switch to icon-only versions with ariaLabel attributes ("Previous Page" / "Next Page") to maintain accessibility without visible labels.

  • All buttons are keyboard-focusable. Users can Tab through pagination controls and activate them with Enter or Space.

  • The component auto-collapses page numbers with ellipsis buttons to reduce cognitive load, especially on smaller screens.

    Additional accessibility test and build content is coming soon, in a new format.


Options

First Page

When currentPage is 1, the Previous button is disabled. The component shows the first few page numbers and the last page.

Copy Code
<nys-pagination currentPage="1" totalPages="12"></nys-pagination>

Middle Page

When the user is in the middle of the result set, the component shows ellipsis on both sides with the current page centered.

Copy Code
<nys-pagination currentPage="6" totalPages="12"></nys-pagination>

Last Page

When currentPage equals totalPages, the Next button is disabled. The component shows the first page and the last few page numbers.

Copy Code
<nys-pagination currentPage="12" totalPages="12"></nys-pagination>

Few Pages

When there are only a handful of pages, all page numbers are shown without ellipsis.

Copy Code
<nys-pagination currentPage="2" totalPages="3"></nys-pagination>

Single Page

When totalPages is 1, the component renders nothing. Pagination is unnecessary when all content fits on one page.

Copy Code
<nys-pagination currentPage="1" totalPages="1"></nys-pagination>

Responsive Behavior

On screens below 768px, the component automatically switches to a condensed layout: Previous and Next buttons become icon-only, and neighboring page numbers are hidden to save space.


Usage

Do

  • Use for large result sets such as search results, data tables, or directory listings where loading everything at once would hurt performance or usability.
  • Use when users need to navigate to a specific part of a result set.
  • Set totalPages based on your data set and page size; update currentPage in response to nys-change events.
  • Don't set currentPage to a value greater than totalPages. The component clamps the value automatically, but your application logic should prevent this.
  • Position the pagination component below the content it controls.
  • Scroll users to the top of the results area when they change pages.

Don't

  • Use when content fits on a single page (fewer than 3–4 screen heights). Show all items instead.
  • Use for step-based workflows where users complete tasks in order. Use <nys-stepper> instead.
  • Use for infinite-scroll patterns such as a news feed.

Properties

Property Type Default
id String ""
name String ""
currentPage Number 1
totalPages Number 1

Style Overrides

There are no existing CSS variables for this component. Explore existing options, or propose a new one with a Component Proposal.


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:

Copy Code
// 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}");
});

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: July 11, 2026