Pagination

A navigation component for paginated content with ellipsis support.

Install

npx @beaket/ui add pagination

Import

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

Examples

States

 
export const AllStates = () => (
  <div className="space-y-8">
    <div>
      <h3 className="mb-4 text-sm font-medium">First Page (Link Mode)</h3>
      <Pagination page={1} totalPages={10} buildPageUrl={buildPageUrl} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Middle Page (Link Mode)</h3>
      <Pagination page={5} totalPages={10} buildPageUrl={buildPageUrl} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Last Page (Link Mode)</h3>
      <Pagination page={10} totalPages={10} buildPageUrl={buildPageUrl} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Few Pages (3)</h3>
      <Pagination page={2} totalPages={3} buildPageUrl={buildPageUrl} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Many Pages with Ellipsis</h3>
      <Pagination page={50} totalPages={100} buildPageUrl={buildPageUrl} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Single Page (Hidden)</h3>
      <p className="text-steel text-sm">Pagination is hidden when totalPages = 1</p>
      <Pagination page={1} totalPages={1} buildPageUrl={buildPageUrl} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Button Mode — First Page</h3>
      <Pagination mode="button" page={1} totalPages={10} onPageChange={() => {}} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Button Mode — Middle Page</h3>
      <Pagination mode="button" page={5} totalPages={10} onPageChange={() => {}} />
    </div>

    <div>
      <h3 className="mb-4 text-sm font-medium">Button Mode — Last Page</h3>
      <Pagination mode="button" page={10} totalPages={10} onPageChange={() => {}} />
    </div>
  </div>
);

Props

NameTypeDefaultDescription
modeundefined | link | button—Use link-based navigation (default). Renders `<a>` tags for SSR-friendly navigation. Use button-based navigation for client-side pagination. Renders `<button>` tags with onClick handlers.
buildPageUrl((page: number) => string) | undefined—Function to build URL for a given page number. Required when mode is "link".
onPageChange((page: number) => void) | undefined—Callback when a page is selected. Required when mode is "button".
page*number—Current page number (1-indexed)
totalPages*number—Total number of pages
maxPageButtonsnumber | undefined—Maximum number of page buttons to show (default: 5) When there are more pages, ellipsis will be shown