Pagination

한눈에#

목록·검색 결과를 페이지 단위로 끊어 이동하는 내비게이션입니다 — 현재 페이지 ±1과 양끝만 남기고 사이를 줄임표(…)로 접습니다.

직접 클릭해 보세요 — 현재 페이지 ±1과 양끝(1, 20)만 남기고 사이를 줄임표(…)로 접습니다.

사용 시점#

목록·검색 결과를 페이지 단위로 끊어 이동하면 Pagination — 편집·정렬이 있는 운영 표는 DataGrid가 합성합니다.

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

변형#

비제어(defaultPage)와 제어(page)를 모두 지원합니다. 비제어는 현재 페이지를 내부에서 소유하고 변경만 알립니다. URL이 진실의 원천이어야 하는 경우 page로 제어하세요 — 클릭은 onPageChange로만 통지하고 현재 페이지는 외부 값을 따릅니다(함수 prop은 서버 MDX로 전달 불가라 코드로 보입니다):

'use client';

// 비제어 — 컴포넌트가 페이지를 소유, 라우터는 부수효과
function ProductListPagination({ totalPages }: { totalPages: number }) {
  const router = useRouter();
  return (
    <Pagination
      totalPages={totalPages}
      defaultPage={1}
      onPageChange={(page) => router.push(`?page=${page}`)}
    />
  );
}

// 제어 — URL search param이 진실의 원천(page가 권위)
function ControlledPagination({ totalPages }: { totalPages: number }) {
  const params = useSearchParams();
  const router = useRouter();
  const page = Number(params.get('page') ?? 1);
  return (
    <Pagination
      totalPages={totalPages}
      page={page}
      onPageChange={(next) => router.push(`?page=${next}`)}
    />
  );
}

크기#

size prop이 없습니다 — 버튼은 시각 32px 정사각형(space.8)에 44px 히트 영역이 확장된 단일 크기입니다.

상태#

• 현재 페이지 — primary-subtle 배경 + primary-text + semibold (aria-current="page")
• 경계 disabled — 1페이지에서 이전, 마지막에서 다음 버튼이 비활성
• hover — surface-hover 배경, focus — 2px focus-ring 링
• 이미 현재인 페이지를 클릭하면 onPageChange가 호출되지 않습니다

Props#

접근성#

• <nav aria-label="페이지네이션"> + ul/li — 랜드마크로 점프 가능합니다
• 현재 페이지는 aria-current="page", 각 페이지 버튼은 aria-label="N 페이지"
• 이전/다음은 아이콘 버튼이라 previousLabel/nextLabel이 접근성 이름입니다
• 줄임표(…)는 장식(aria-hidden) — 낭독되지 않습니다
• 경계 비활성은 disabled 속성 — 포커스 순서에서 자연스럽게 제외됩니다

토큰#

component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).