Skip to main content
USWDS + Tailwind

Pagination

Help visitors move through paginated content with bounded and unbounded pagination patterns.

Examples

Bounded

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
pagination-bounded-demo.tsx
import { Pagination } from '@uswds-tailwind/react/pagination'


export default function PaginationBoundedDemo() {
  return (
    <Pagination.Root currentPage={6} pageCount={8}>
      <Pagination.List>
        {({ pages }) => (
          <>
            <Pagination.PrevTrigger />
            {pages.map((page, index) =>
              page.type === 'page'
                ? <Pagination.Item key={page.value} value={page.value} />
                : <Pagination.Ellipsis key={`ellipsis-${index}`} />,
            )}
            <Pagination.NextTrigger />
          </>
        )}
      </Pagination.List>
    </Pagination.Root>
  )
}

Pages shortcut

Pagination.Pages renders a Pagination.Item for each visible page and a Pagination.Ellipsis for each gap. Inside Pagination.List, this:

<Pagination.List>
  <Pagination.PrevTrigger />
  <Pagination.Pages />
  <Pagination.NextTrigger />
</Pagination.List>

is shorthand for the render function used in the full example above:

<Pagination.List>
  {({ pages }) => (
    <>
      <Pagination.PrevTrigger />
      {pages.map((page, index) =>
        page.type === 'page'
          ? <Pagination.Item key={page.value} value={page.value} />
          : <Pagination.Ellipsis key={'ellipsis-' + index} />,
      )}
      <Pagination.NextTrigger />
    </>
  )}
</Pagination.List>

Unbounded

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
pagination-unbounded-demo.tsx
import { Pagination } from '@uswds-tailwind/react/pagination'


export default function PaginationUnboundedDemo() {
  return (
    <Pagination.Root currentPage={6}>
      <Pagination.List>
        <Pagination.PrevTrigger />
        <Pagination.Pages />
        <Pagination.NextTrigger />
      </Pagination.List>
    </Pagination.Root>
  )
}

Component API

Place List inside Root. Use PrevTrigger, NextTrigger, Item, Ellipsis, or the Pages shortcut to build page navigation.

Root<nav>

Owns the current page.

PropTypeDefaultDescription
currentPagenumber1Initial page or controlled page when onPageChange is supplied.
pageCountnumber—Total page count.
onPageChange(page: number) => void—Receives page changes; supply currentPage to control the state.

List<ul>

Contains navigation items.

PropTypeDescription
childrenReactNode | ({ pages: PageSlot[] }) => ReactNodeRenders items directly or from computed page slots.

PrevTrigger<button>

Moves to the previous page.

NextTrigger<button>

Moves to the next page.

Item<li>

Wraps a button by default. Button props and page-state attributes apply to that inner button; render can replace it with a custom control.

PropTypeDescription
valuenumber (required)Page number.
render(props: PaginationItemRenderProps) => ReactNodeRenders a custom page control.

Ellipsis<li>

Marks a gap in the visible page sequence.

Pages

Renders Item and Ellipsis parts from the computed page sequence.

PropTypeDescription
renderPaginationItemProps["render"]Customizes the page controls.