Pagination

Workbench 불러오는 중…

Component intent의도와 경계 읽기

page/pageSize/total 세 값만 받으면 페이지 버튼(boundary + sibling + ellipsis), "X-Y / Total" 정보 줄, ←/→ 키보드 이동을 자체 계산해 제공하는 controlled 컴포넌트다. 페이지 수가 boundaryCount·siblingCount 로 정해지는 한계 이하면 ellipsis 없이 전부 표시한다. compact 모드는 좁은 컨테이너/모바일용으로 이전/다음 + "현재/총" 만 노출한다. 숫자는 tabular-nums 로 자리수를 시각적으로 안정시키고 총량은 ko-KR 콤마로 포맷한다.

01기본 (controlled)tsxfragment

import { Pagination } from "@axe/ui";const [page, setPage] = useState(1);<Pagination page={page} pageSize={20} total={480} onPageChange={setPage} />

02compact (모바일)tsxfragment

import { Pagination } from "@axe/ui";<Pagination page={3} pageSize={20} total={480} compact onPageChange={setPage} />

03CSS-only 정적 바 (비-React)htmlfragment

<nav class="axe-pagination axe-pagination--size-md" aria-label="Pagination">  <div class="axe-pagination__info">    <span class="axe-pagination__info-range">1-20</span>    <span class="axe-pagination__info-sep"> / </span>    <span class="axe-pagination__info-total">480</span>  </div>  <ul class="axe-pagination__list">    <li><button class="axe-pagination__btn axe-pagination__btn--nav" aria-label="이전 페이지" disabled aria-disabled="true">‹</button></li>    <li><button class="axe-pagination__btn axe-pagination__btn--active" aria-current="page" aria-label="1페이지 · 현재">1</button></li>    <li><button class="axe-pagination__btn" aria-label="2페이지">2</button></li>    <li aria-hidden="true"><span class="axe-pagination__ellipsis">…</span></li>    <li><button class="axe-pagination__btn" aria-label="24페이지">24</button></li>    <li><button class="axe-pagination__btn axe-pagination__btn--nav" aria-label="다음 페이지">›</button></li>  </ul></nav>

이름	타입	필수	기본값	설명
`page`	`number`	필수	—	1-based 현재 페이지. 내부적으로 [1, totalPages] 로 clamp.
`pageSize`	`number`	필수	—	페이지당 항목 수 (정보 줄·totalPages 계산에 사용).
`total`	`number`	필수	—	전체 항목 수 (페이지 수가 아님). 0 이면 페이지 리스트 숨김.
`onPageChange`	`(page: number) => void`	필수	—	페이지 변경 콜백. 상위 상태를 갱신 (controlled).
`siblingCount`	`number`	—	`1`	활성 페이지 좌우로 보여줄 페이지 수.
`boundaryCount`	`number`	—	`1`	시작/끝에서 항상 보여줄 페이지 수.
`showInfo`	`boolean`	—	`true`	"X-Y / Total" 정보 줄 표시 (compact 시 무시).
`size`	`"sm" \| "md"`	—	`"md"`	버튼 크기. md 는 기본(별도 CSS 규칙 없음), sm 은 28px 축소.
`compact`	`boolean`	—	`false`	모바일/좁은 컨테이너용 — 이전/다음 + "현재/총" 만 표시. size 무시.
`ariaLabel`	`string`	—	`"Pagination · 페이지 네비게이션 (←/→ 키)"`	SR 용 nav label.
`...rest`	`React.HTMLAttributes<HTMLElement>`	—	—	나머지는 루트 <nav> 로 전파 (onChange 는 Omit).

클래스	안정성	용도
`.axe-pagination`	stable	<nav> 루트 (flex space-between, tabular-nums).
`.axe-pagination--size-sm`	stable	sm 크기 변형 (버튼 28px).
`.axe-pagination--compact`	stable	compact 모바일 변형 (중앙 정렬, 이전/다음 + n/총).
`.axe-pagination__info`	stable	"X-Y / Total" 정보 줄.
`.axe-pagination__info-range`	internal	범위(X-Y) — primary 색.
`.axe-pagination__info-sep`	internal	정보 줄 구분자.
`.axe-pagination__info-total`	internal	총량.
`.axe-pagination__list`	stable	페이지 버튼 <ul> (←/→ 키 핸들러가 붙는 영역).
`.axe-pagination__btn`	stable	페이지/nav 버튼 (32px, hover/focus/disabled).
`.axe-pagination__btn--active`	stable	현재 페이지 버튼 (accent 배경).
`.axe-pagination__btn--nav`	stable	이전/다음 (‹ ›) 버튼.
`.axe-pagination__ellipsis`	stable	생략(…) 표시.
`.axe-pagination__compact-label`	internal	compact 모드 "n / 총" 컨테이너.
`.axe-pagination__compact-current`	internal	compact 현재 페이지 (semibold).
`.axe-pagination__compact-sep`	internal	compact 구분자.
`.axe-pagination__compact-total`	internal	compact 총 페이지.

비-React 소비 노트

시각 바는 위 html 예제 마크업으로 재현 가능하나, 페이지 전환·←/→ 키·ellipsis 계산은 컴포넌트 JS(onPageChange)가 담당한다. CSS-only 는 정적 표시용이며 버튼은 동작하지 않는다. size="md" 는 emit 되지만 별도 CSS 규칙이 없는 기본값이다.

권장

page 는 1-based 로 넘기고 onPageChange 에서 상위 상태를 갱신 (controlled).
좁은 컨테이너/모바일은 compact 사용.
큰 total 은 siblingCount/boundaryCount 로 표시 밀도 조절.

지양

total 을 페이지 수로 착각 말 것 — 전체 항목 개수다.
onPageChange 없이 순수 표시로만 쓰지 말 것 (버튼이 controlled).

먼저 보고, 그다음 계약을 읽습니다

예제

Props

.axe-* 클래스 계약

권장 · 지양