Pagination

Shows links between pages of results.

pagination-basic-demo.tsx

"use client";import { CaretLeftIcon, CaretRightIcon } from "@phosphor-icons/react";import { useState } from "react";import {  Pagination,  PaginationItem,  PaginationLink,  PaginationList,} from "@/components/vip-ui/pagination";export function PaginationBasicDemo() {  const [page, setPage] = useState(1);  return (    <Pagination>      <PaginationList className="flex-nowrap gap-1 sm:gap-2">        <PaginationItem>          <PaginationLink            isDisabled={page === 1}            aria-label="Previous page"            onPress={() => {              setPage((current) => current - 1);            }}          >            <CaretLeftIcon aria-hidden="true" />            <span className="hidden sm:inline">Previous</span>          </PaginationLink>        </PaginationItem>        {[1, 2, 3].map((number) => (          <PaginationItem key={number}>            <PaginationLink              isCurrent={page === number}              onPress={() => {                setPage(number);              }}              aria-label={`Page ${number}`}            >              {number}            </PaginationLink>          </PaginationItem>        ))}        <PaginationItem>          <PaginationLink            isDisabled={page === 3}            aria-label="Next page"            onPress={() => {              setPage((current) => current + 1);            }}          >            <span className="hidden sm:inline">Next</span>            <CaretRightIcon aria-hidden="true" />          </PaginationLink>        </PaginationItem>      </PaginationList>    </Pagination>  );}

Installation

CLI

Manual

The CLI adds the files, packages, theme variables, and Tailwind plugin that this component uses. Before you run it, set up your project.

npm

yarn

pnpm

bun

pnpm dlx shadcn@latest add https://vip-ui.dev/r/vip-pagination.json

Composition

Pagination
- PaginationList
  - PaginationItemRepeats
    - PaginationLink
    - PaginationEllipsis
      Use it in place of a link.

URL-synced pages

Keep the page in the URL, so the Back button and shared links work. RouterProvider sends link presses to your router.

Item 1
Item 2
Item 3

pagination-demo.tsx

"use client";import { CaretLeftIcon, CaretRightIcon } from "@phosphor-icons/react";import { useSyncExternalStore } from "react";import { RouterProvider } from "react-aria-components";import {  Pagination,  PaginationItem,  PaginationLink,  PaginationList,} from "@/components/vip-ui/pagination";const items = Array.from({ length: 9 }, (_, index) => `Item ${index + 1}`);function subscribe(callback: () => void) {  window.addEventListener("popstate", callback);  window.addEventListener("pagination-change", callback);  return () => {    window.removeEventListener("popstate", callback);    window.removeEventListener("pagination-change", callback);  };}function currentPage() {  const match = /^([1-3])$/.exec(    new URLSearchParams(window.location.search).get("page") ?? "",  );  return match ? Number(match[1]) : 1;}function navigate(href: string) {  window.history.pushState(null, "", new URL(href, window.location.href));  window.dispatchEvent(new Event("pagination-change"));}export function PaginationDemo() {  const page = useSyncExternalStore(subscribe, currentPage, () => 1);  return (    <RouterProvider navigate={navigate}>      <div className="grid w-full max-w-md gap-5">        <ul className="divide-y divide-border rounded-lg border border-border bg-card px-4 text-sm shadow-[var(--shadow-card)]">          {items.slice((page - 1) * 3, page * 3).map((item) => (            <li className="flex min-h-12 items-center" key={item}>              {item}            </li>          ))}        </ul>        <Pagination>          <PaginationList className="w-full flex-nowrap gap-1 sm:gap-2">            <PaginationItem className="flex-1 justify-end">              <PaginationLink                href={`?page=${page - 1}#preview`}                isDisabled={page === 1}                aria-label="Previous page"              >                <CaretLeftIcon aria-hidden="true" />                <span className="hidden sm:inline">Previous</span>              </PaginationLink>            </PaginationItem>            {[1, 2, 3].map((number) => (              <PaginationItem key={number}>                <PaginationLink                  href={`?page=${number}#preview`}                  isCurrent={number === page}                  aria-label={`Page ${number}`}                >                  {number}                </PaginationLink>              </PaginationItem>            ))}            <PaginationItem className="flex-1 justify-start">              <PaginationLink                href={`?page=${page + 1}#preview`}                isDisabled={page === 3}                aria-label="Next page"              >                <span className="hidden sm:inline">Next</span>                <CaretRightIcon aria-hidden="true" />              </PaginationLink>            </PaginationItem>          </PaginationList>        </Pagination>      </div>    </RouterProvider>  );}

Sizes

Use sm or xs below a dense table.

pagination-sizes-demo.tsx

"use client";import { CaretLeftIcon, CaretRightIcon } from "@phosphor-icons/react";import {  Pagination,  PaginationItem,  PaginationLink,  PaginationList,} from "@/components/vip-ui/pagination";import type { Size } from "@/components/vip-ui/size";export function PaginationSizesDemo() {  return (    <div className="flex flex-col items-center gap-4">      <ResultsPagination size="xs" />      <ResultsPagination size="sm" />      <ResultsPagination />    </div>  );}function ResultsPagination({ size }: { size?: Size }) {  return (    <Pagination size={size} aria-label="Results">      <PaginationList className="flex-nowrap">        <PaginationItem>          <PaginationLink href="#preview" aria-label="Previous page">            <CaretLeftIcon aria-hidden="true" />          </PaginationLink>        </PaginationItem>        <PaginationItem>          <PaginationLink href="#preview" isCurrent aria-label="Page 1">            1          </PaginationLink>        </PaginationItem>        <PaginationItem>          <PaginationLink href="#preview" aria-label="Page 2">            2          </PaginationLink>        </PaginationItem>        <PaginationItem>          <PaginationLink href="#preview" aria-label="Page 3">            3          </PaginationLink>        </PaginationItem>        <PaginationItem>          <PaginationLink href="#preview" aria-label="Next page">            <CaretRightIcon aria-hidden="true" />          </PaginationLink>        </PaginationItem>      </PaginationList>    </Pagination>  );}

API reference

Pagination

size: "xs" | "sm" | "md" | "lg" | "xl" = "md": Uses the Button heights for each link and the ellipsis. Set it on Pagination or on one PaginationLink.
aria-label: string = "Pagination": Names the navigation landmark. Change it when a page has more than one pagination.

PaginationLink

href: string: The URL of the page. Without it, handle onPress to change the page.
isCurrent: boolean = false: Shows the link as the current page and sets aria-current="page". The current-page marker glides to the new link.
isDisabled: boolean = false: Keeps the link visible but stops navigation. The link leaves the Tab order.
onPress: (event: PressEvent) => void: Called when the link is pressed.
size: "xs" | "sm" | "md" | "lg" | "xl": Sets the size of this link. Without it, the link uses the size of the Pagination, or md.