Components

Pagination

Docs

Pagination API 사용가이드입니다. 조합 예시는 Overview를 참고하세요.

API

controlled page · totalPages · onPageChange가 필수입니다. showTotalPages로 현재/전체 요약을, siblings·selectedClassName으로 노출·색을 조절합니다.

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

const [page, setPage] = useState(1);

<Pagination page={page} totalPages={30} onPageChange={setPage} />

{/* 현재 / 전체 페이지 요약 */}
<Pagination
  page={page}
  totalPages={30}
  onPageChange={setPage}
  showTotalPages
/>

{/* 요약 문구 커스텀 */}
<Pagination
  page={page}
  totalPages={30}
  onPageChange={setPage}
  showTotalPages
  labels={{ totalPages: (n, total) => `${n} / ${total} 페이지` }}
/>

{/* 소비 앱 아이콘 */}
<Pagination
  page={page}
  totalPages={30}
  onPageChange={setPage}
  previousIcon={<AppChevronLeft className="size-5" />}
  nextIcon={<AppChevronRight className="size-5" />}
/>

Props

Name	Type	Default	Description
`page`Required	`number`	—	현재 페이지 (1-based). controlled.
`totalPages`Required	`number`	—	전체 페이지 수.
`onPageChange`Required	`(page: number) => void`	—	페이지 변경 콜백. Prev/Next · 번호 클릭 시 호출됩니다.
`siblings`	`number`	`3`	현재 페이지 기준 앞·뒤에 보여줄 페이지 수. 디자인 가이드 기본값 3.
`showEllipsis`	`boolean`	`true`	true면 양 끝 페이지를 유지하고 중간을 … 로 생략합니다. false면 현재 주변 윈도우만 표시합니다.
`showTotalPages`	`boolean`	`false`	true면 컨트롤 아래에 page n / total 요약을 표시합니다. 문구는 labels.totalPages로 커스텀합니다.
`disabled`	`boolean`	`false`	전체 컨트롤 비활성.
`selectedClassName`	`string`	—	선택 페이지 버튼에 추가할 className. 기본은 bg-surface-primary.
`itemClassName`	`string`	—	페이지 번호 버튼 공통 className.
`controlClassName`	`string`	—	Prev/Next 버튼 className.
`ellipsisClassName`	`string`	—	생략(…) 표시 className.
`className`	`string`	—	nav 루트 className. 예: w-full justify-end.
`labels`	`{ root?, previous?, next?, page?, totalPages? }`	—	aria-label · 요약 문구 커스텀. totalPages는 showTotalPages일 때 (page, total) => string.
`previousIcon`	`ReactNode`	`<DefaultPreviousIcon /> (size-4 md:size-6)`	Prev 아이콘. 미전달 시 DefaultPreviousIcon(기본 표시 size-4 md:size-6). 소비 앱 노드를 넘기면 교체하며, 크기는 그 노드 className으로 지정합니다.
`nextIcon`	`ReactNode`	`<DefaultNextIcon /> (size-4 md:size-6)`	Next 아이콘. 미전달 시 DefaultNextIcon(기본 표시 size-4 md:size-6). previousIcon과 동일 규칙.

Events

Name	Signature	Description
`onPageChange`	`(page: number) => void`	유효 범위(1…totalPages)로 clamp된 페이지가 전달됩니다.

Notes

소비 앱 필수: React 19, Tailwind CSS v4, ClaBi tokens.css(+ @theme 매핑), clsx.
clsx 패키지가 필수입니다. className 병합에 import { clsx } from "clsx" 를 사용합니다.
페이지는 1-based입니다.
showTotalPages는 기본 false입니다. true면 하단에 page n / total 요약을 띄우며 aria-live="polite"입니다.
기본 선택 색은 tokens(bg-surface-primary). 커스텀은 selectedClassName.
생략(…)은 button이 아니며 aria-hidden입니다.
현재 페이지 버튼에는 aria-current="page"가 붙습니다.
맨 앞/맨 뒤(<< >>) 전용 버튼은 없습니다. 1·마지막 번호와 Prev/Next로 이동합니다.
기본 Prev/Next는 DefaultPreviousIcon / DefaultNextIcon입니다. className에 size-*가 없으면 size-4 md:size-6, 있으면 className 크기가 우선합니다.
getPaginationRange({ page, totalPages, siblings, showEllipsis })를 export합니다.