Pagination React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Pagination is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Pagination from @/components/ui/pagination.

import { useState } from "react"
import { Pagination } from "@/components/ui/pagination"

export function InvoicesFooter({ total }: { total: number }) {
  const [page, setPage] = useState(1)
  const [pageSize, setPageSize] = useState(20)
  return (
    <Pagination
      total={total}
      page={page}
      onPageChange={setPage}
      pageSize={pageSize}
      onPageSizeChange={setPageSize}
      showPageSize
      locale="en-US"
      labels={{
        summary: (a, b, t) => `${a}\u2013${b} of ${t} invoices`,
        pageSize: "Invoices per page",
      }}
    />
  )
}

Props

• page
  number

  The current page, 1-based, controlled. A page beyond pageCount renders as given with next disabled; it is never corrected silently.

• defaultPagedefault 1
  number

  The starting page while uncontrolled.

• onPageChange
  (page: number) => void

  Fires on every page change: a click, an arrow key, the jump field, the compact page picker or a page size change.

• pageCount
  number

  Total pages. Default: ceil(total / pageSize). 0 renders only the summary ("No results").

• total
  number

  The item count, for the page count and the summary ("1 to 20 of 318"). Without it the summary reads "Page 5 of 16".

• pageSize
  number

  Items per page, controlled.

• defaultPageSizedefault "20"
  number

  Items per page while uncontrolled; also used when total is given without pageSize.

• onPageSizeChange
  (pageSize: number) => void

  Fires when the page size select changes. The page moves so the first visible item stays on screen: page = floor(firstIndex / newSize) + 1.

• pageSizeOptionsdefault "[10, 20, 50, 100]"
  number[]

  The choices in the page size select.

• variantdefault "numbers"
  "numbers" | "simple" | "compact" | "load-more"

  numbers: ‹ 1 … 4 5 6 … 20 ›. simple: Previous / Next buttons with the summary between. compact: ‹ Page 5 of 20 › where the text opens a page picker. load-more: a full-width button for feeds with a remaining count and a progress bar.

• mobileVariantdefault "compact"
  "compact" | "simple" | "numbers"

  What renders while the pagination is narrower than 640px: a phone, or a card or side panel on desktop (a CSS container query). Both layouts are in the server HTML and CSS picks one, so nothing jumps after hydration. numbers drops the sibling pages there so it fits 360px.

• siblingCountdefault 1
  number

  Pages shown on each side of the current one. The slots come from getPageRange(page, pageCount, siblingCount, boundaryCount), exported for custom UIs; their count stays constant while the page moves.

• boundaryCountdefault 1
  number

  Pages always shown at each end.

• showFirstLastdefault false
  boolean

  Adds « and » buttons that jump to the first and last page. Below 640px the numbers row drops them (its boundary pages already reach the ends) so it fits 360px.

• showSummarydefault true
  boolean

  Shows "1 to 20 of 318" (a polite live region, so screen readers hear each change once).

• showPageSizedefault false
  boolean

  Shows the page size select ("20 per page"); a bottom sheet on phones.

• showJumpdefault false
  boolean

  Shows a small "Go to" number field: Enter jumps, out-of-range numbers clamp. Hidden on phones when the compact picker is there.

• aligndefault "between"
  "start" | "center" | "end" | "between"

  between puts the summary at the start and the pages at the end; the others keep them together.

• sizedefault "md"
  "sm" | "md" | "lg"

  Button height 32 / 40 / 48px (md is 44px on touch). Page buttons are square and grow for long numbers.

• activeVariantdefault "soft"
  "soft" | "solid" | "outline"

  The current page's pill: a soft tint (like tabs), the solid tone fill, or an outline.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape of every button, scaled with the size like the button's; full makes round page pills.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The current page's color (and the load-more button and bar). Neutral is black in light mode and white in dark mode.

• colordefault ""
  string

  Any CSS color for the current page; replaces the tone. Leave empty to use the tone.

• loadingdefault false
  boolean

  The next page is loading: the control you pressed shows a spinner and the rest are disabled until it turns false.

• disableddefault false
  boolean

  Dims and blocks every control.

• autoLoaddefault false
  boolean

  load-more only: loads the next batch on its own when the button scrolls within 200px (IntersectionObserver in the nearest scroll container).

• localedefault ""
  string

  Number formatting ("1.250" in de-DE, "1,250" in en-US). Empty uses the LocaleProvider, then the page language.

• getPageHref
  (page: number) => string

  Renders every page as a link (NavLink through the app's router link) instead of a button: crawlable, open in a new tab, router-friendly. Arrow keys, the jump field and the page picker navigate too.

• linkComponent
  (props: LinkComponentProps) => ReactNode

  The link component for this instance; default the LinkProvider's, else a plain <a>.

• hasNextPage
  boolean

  Cursor pagination without a known count: when set and neither total nor pageCount is, only previous / next render, next disabled when false.

• hasMore
  boolean

  load-more: whether there is more to load. Default loadedCount < total. false shows the end message.

• onLoadMore
  (() => void | Promise<unknown>)

  load-more: called by the button (or autoLoad). Return a promise to show the loading state until it settles.

• loadedCount
  number

  load-more: items already on screen, for "Showing 40 of 318", the remaining count and the bar.

• labels
  Partial<PaginationLabels>

  Every string, English by default: navigation, previous, next, first, last, page(n), pageOf(page, count), summary(from, to, total), empty, pageSize, perPage(size), jump, loadMore(count), remaining(count), loading, end, showing(shown, total). Numbers arrive formatted for the locale. DEFAULT_PAGINATION_LABELS is exported to spread and override.

• classNames
  Partial<Record<"meta" | "summary" | "controls" | "list" | "item" | "link" | "ellipsis" | "indicator" | "previous" | "next" | "first" | "last" | "size" | "jump" | "compact" | "loadMore" | "loadMoreStatus" | "loadMoreBar", string>>

  Extra classes for the inner parts.

Parts

FAQ

Used in

More React navigation components