Pagination - National Design System

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. Default controls are buttons you drive through nds:pagination:change (SPA); add data-page-url="?page={page}" to emit navigable links for no-JS full-reload server pagination. For a runtime count change, call NDS.Pagination.setTotalPages()
• 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, put nds-paged-content on the <tbody> itself and add nds-page-item on each <tr>. A wrapper around the table would be hidden until pagination initializes; the tbody shows its skeleton rows instead
• Both <button> and <a> elements work inside pagination items. Use buttons for client-side navigation, anchors for distinct URLs
• Bind a nav to its content by id — data-auto-pagination="gridId" matching the wrapper's id (the same convention as filter's data-filter-target). Omit the value to bind the immediately-preceding wrapper instead
• Keep nds-page-item (your content items) distinct from nds-pagination-item (the nav's <li> controls) — similar names, opposite roles
• For server or AJAX pagination, listen for nds:pagination:change (its detail.page is the resolved page), load that page, then call NDS.Pagination.setPage() to highlight it (calling it once the response lands also scrolls the content back into view, with no delay to guess). When a new query changes the total page count, call NDS.Pagination.setTotalPages() to rebuild the controls (it keeps the current page; pass a page number to jump). NDS owns the nav UI, you own the data
• Attach your logic to the nav, not to individual page buttons: listen for nds:pagination:change or give each page a distinct <a href>. Collapsing rebuilds the page buttons and dropdown pages render on demand, so custom classes, data-* attributes, href, and inline onclick survive on author-written markup, but a listener added with addEventListener on a button does not
• For content pagination, adding or removing nds-page-item elements re-paginates automatically and keeps the current page, no re-init needed, at any nesting (cards, list items, table rows). A wholesale content swap that injects a brand-new nav (e.g. a filter's AJAX HTML mode) still needs NDS.Pagination.reinit(), or have the server return it already paginated
• Don't paginate a continuously growing feed. Use Scroll More for load-on-scroll content where the total count isn't fixed
• Don't use pagination for a linear, must-finish-in-order flow like a form wizard. Reach for Stepper instead

Modifier Classes

Data Attributes

CSS Custom Properties

JavaScript API