Pagination and Load more

01Preview

Change the controls to try every supported combination. Make the window narrow to see the auto variant switch to its compact form.

import { Pagination } from '@nuton/ui'

<Pagination
  page={page}
  pageCount={12}
  getHref={(p) => `/library?page=${p}`}
  labels={{ nav: 'Library pages' }}
/>

02Installation

pnpm add @nuton/ui @nuton/tokens

npm install @nuton/ui @nuton/tokens

yarn add @nuton/ui @nuton/tokens

import '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'

03Usage

import { LoadMore, Pagination } from '@nuton/ui'

// Each page has its own URL: links
<Pagination page={page} pageCount={12} getHref={(p) => `/library?page=${p}`} labels={{ nav: 'Library pages' }} />

// The list changes in place: buttons
<Pagination page={page} pageCount={12} onPageChange={setPage} />

// Learners add the next batch at the end of the list
<LoadMore shown={courses.length} total={120} loading={isFetching} onLoadMore={fetchNextPage} />

• Load more suits browsing: a library learners scroll through. It is what the live library uses. Pagination suits finding things again: search results, long tables, anything people share or return to.
• Prefer links (getHref) when pages have URLs: they work without JavaScript and can open in a new tab. Pass a router's link with linkAs.
• Name the landmark after what it pages (“Library pages”), especially when a page has more than one navigation.
• Don't load more automatically on scroll alone. Keyboard and screen-reader users can never reach what comes after the list.
• Pagination has no hooks, so it renders in server components. LoadMore is a client component.

04Variants and sizes

One size. Pagination has three layouts; LoadMore has a count and a button.

Numbered

Previous, page numbers with gaps, Next. The number of slots stays the same as the page changes, so the arrows don't jump.

<Pagination page={6} pageCount={12} getHref={href} variant="numbers" />

Compact

“Page 3 of 12” between the arrows, for phones and narrow columns. The default auto variant switches to it below 30rem of its container's width.

<Pagination page={3} pageCount={12} getHref={href} variant="compact" showFirstLast />

First and last

<Pagination page={20} pageCount={40} getHref={href} variant="numbers" showFirstLast siblingCount={2} />

05States and interactions

State tokens

Set on .nu-pagination.

06Composition examples

A paged library

Button mode: the list changes in place. Focus stays on the control you used, and the compact text is a polite live region so the new page is announced.

const [page, setPage] = useState(1)

<ul aria-label={`Courses, page ${page} of ${pageCount}`}>{/* this page's courses */}</ul>
<Pagination page={page} pageCount={pageCount} onPageChange={setPage} align="center" labels={{ nav: 'Course list pages' }} />

Load more courses

The live library pattern. New courses are added after the last one; the count updates and “12 more courses loaded” is announced. When everything has loaded, the button goes and focus moves to the count.

<ul aria-label="Courses">{courses.map(…)}</ul>
<LoadMore
  shown={courses.length}
  total={48}
  loading={loading}
  onLoadMore={loadNextBatch}
  labels={{ button: 'Load more courses', loaded: (added, shown, total) => `${added} more courses loaded. Showing ${shown} of ${total}.` }}
/>

07API reference

Pagination props

LoadMore props

Accessibility

You must: name the landmark when there is more than one, keep the list's order stable as items are added, and never load more on scroll alone.

08Guidelines and related components

Do and don't

Related components

• ButtonThe Load more button.
• BreadcrumbsShows where a page sits in the hierarchy.
• Segmented controlSwitch the library between grid and list.
• SkeletonPlaceholders while the next batch loads.