Pagination - National Design System

Navigate large data sets with numbered page controls, or automatically split grids, lists, and tables into pages with built-in content management

Standard Pagination

Numbered page controls with previous and next arrows for stepping through content

Data-Driven Pagination

Set a page count and optional active page on an empty nav element, and the component generates all controls automatically

Automatic Ellipsis Collapse

When page count exceeds five, middle pages collapse into a dropdown for compact navigation

Paginated Grid

Automatically split grid items across pages by marking children with nds-page-item and placing a data-auto-pagination nav after the container

Paginated Table

Table rows paginate the same way as grid items, with the nds-page-item class on each body row

Built-in Features

Auto-initialization

Scans for nds-pagination elements on the page. Active states, disabled buttons, and ellipsis collapse configure themselves from the markup.

Ellipsis Collapse

Paginations with more than five pages automatically collapse middle pages into a dropdown menu, keeping the first three and last page visible.

Content Pagination

Add data-auto-pagination to any nds-pagination after a nds-paged-content container and the pagination controls, page visibility, and scroll behavior are handled automatically.

Filter-Aware Refresh

When used with filtered content, call NDS.Pagination.refresh() to recalculate page counts and reset to page one with only visible items.

Responsive Adaptation

Buttons shrink on mobile viewports and content pagination watches for --per-page changes on resize, rebuilding pages to match the new layout.

Programmatic Control

Navigate to any page, refresh after content changes, or create new pagination instances through the NDS.Pagination API.

Usage Guidelines

Best Practices

  • Use content pagination (data-auto-pagination) for items already in the DOM: card grids, table rows, or list items
  • Use manual pagination when each page number links to a different URL or triggers a server-side request
  • Use data-driven generation (data-total-pages) when you know the page count but want the component to build the controls
  • Do not paginate fewer than two pages. Auto-pagination hides controls automatically when all items fit
  • Set --per-page to match your grid column count so each page fills the layout. Update it in media queries for responsive grids
  • For tables, wrap the table in nds-paged-content and add nds-page-item on each <tr> in <tbody>. The table wrapper is added automatically
  • Both <button> and <a> elements work inside pagination items. Use buttons for client-side navigation, anchors for distinct URLs

Modifier Classes

Class Applied to Description
nds-md .nds-pagination Medium size, 32px buttons
nds-sm .nds-pagination Small size, 24px buttons
nds-paged-content Content wrapper Marks a container whose nds-page-item children should be paginated
nds-page-item Content children Marks individual items (cards, rows, list items) as pageable content

Data Attributes

Attribute Description
data-auto-pagination Add to nds-pagination to enable content-based auto-pagination from the preceding nds-paged-content container
data-total-pages="N" Set on an empty nds-pagination to auto-generate N page buttons. Optionally add data-active-page="N" to set the initial page (defaults to 1)
data-state="active" Set on a page button to mark it as the current page. Updated automatically on navigation

CSS Custom Properties

Property Default Description
--pagination-margin-top var(--spacing-2xl) Space above the pagination nav
--per-page 5 Items per page in auto-pagination. Set on the nds-paged-content container

JavaScript API

// Initialize all pagination on the page NDS.Pagination.init(); // Initialize auto-pagination (data-auto-pagination + nds-paged-content) NDS.Pagination.initAuto(); // Create a single pagination instance const instance = NDS.Pagination.create(element); // Navigate to a specific page NDS.Pagination.setPage(containerElement, 3); // Refresh after filtering (recalculates pages from visible items) NDS.Pagination.refresh(contentContainer);
Was this page useful?
60% of users said Yes from 2843 Feedbacks