7onicDESIGN SYSTEM

Pagination

Pagination은 대량의 데이터나 콘텐츠를 페이지 단위로 나눠 원하는 페이지로 이동할 수 있게 하는 내비게이션 컴포넌트입니다. 표시할 페이지 범위와 양 끝 페이지 수를 세밀하게 설정할 수 있으며, 생략 기호(…)가 포함된 페이지 범위를 자동으로 계산합니다.

3
Variants
5
Sizes
4
Navigation
Pure
React

Playground

Preview
DdefaultPage 1/20
Variant
Color
Size
Radius
Pages
Options
const [page, setPage] = useState(1)

<Pagination total={20} value={page} onChange={setPage}>
  <Pagination.Content>
    <Pagination.Item>
      <Pagination.Previous />
    </Pagination.Item>
    <Pagination.Items />
    <Pagination.Item>
      <Pagination.Next />
    </Pagination.Item>
  </Pagination.Content>
</Pagination>

Variants

Default
활성 페이지에 솔리드 배경 적용, 가장 일반적인 스타일
기본 UI
Outline
테두리 있음, 활성 페이지는 솔리드 배경 적용
폼, 리스트
Ghost
활성 페이지에 은은한 하이라이트, 최소한의 시각적 존재감
보조 UI

Sizes

xs
높이28px
폰트12px
아이콘14px
sm
높이32px
폰트13px
아이콘14px
default
높이36px
폰트14px
아이콘16px
lg
높이40px
폰트14px
아이콘16px
xl
높이48px
폰트16px
아이콘16px

Features

Edge Navigation (withEdges)

첫 페이지/마지막 페이지 이동 버튼 표시, 많은 페이지를 빠르게 이동할 때 유용

<Pagination total={20} defaultValue={10} withEdges>
  <Pagination.Content>
    <Pagination.Item><Pagination.First /></Pagination.Item>
    <Pagination.Item><Pagination.Previous /></Pagination.Item>
    <Pagination.Items />
    <Pagination.Item><Pagination.Next /></Pagination.Item>
    <Pagination.Item><Pagination.Last /></Pagination.Item>
  </Pagination.Content>
</Pagination>

Loop Navigation (loop)

마지막 페이지에서 첫 페이지로, 첫 페이지에서 마지막 페이지로 순환 이동

<Pagination total={5} defaultValue={5} loop>
  <Pagination.Content>
    <Pagination.Item><Pagination.Previous /></Pagination.Item>
    <Pagination.Items />
    <Pagination.Item><Pagination.Next /></Pagination.Item>
  </Pagination.Content>
</Pagination>

Disabled State

모든 조작 비활성화, 데이터 로딩 중 사용

<Pagination total={10} defaultValue={3} disabled>
  <Pagination.Content>
    <Pagination.Item><Pagination.Previous /></Pagination.Item>
    <Pagination.Items />
    <Pagination.Item><Pagination.Next /></Pagination.Item>
  </Pagination.Content>
</Pagination>

Custom Icons

icon prop으로 내장 아이콘을 원하는 ReactNode로 교체

<Pagination total={10} defaultValue={5}>
  <Pagination.Content>
    <Pagination.Item>
      <Pagination.Previous icon={
        <svg className="icon-sm" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
          <path strokeLinecap="round" strokeLinejoin="round" d="M10 19l-7-7m0 0l7-7m-7 7h18" />
        </svg>
      } />
    </Pagination.Item>
    <Pagination.Items />
    <Pagination.Item>
      <Pagination.Next icon={
        <svg className="icon-sm" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
          <path strokeLinecap="round" strokeLinejoin="round" d="M14 5l7 7m0 0l-7 7m7-7H3" />
        </svg>
      } />
    </Pagination.Item>
  </Pagination.Content>
</Pagination>

API

Component Structure

Pagination— Pure React
.Content.Item.LinkProps.PreviousProps.NextProps.FirstProps.LastProps.Ellipsis.Items

Props

Pagination

total1
number

전체 페이지 수

valueundefined
number

현재 페이지 (controlled 모드)

defaultValue1
number

초기 페이지 (uncontrolled 모드)

onChangeundefined
(page: number) => void

페이지 변경 시 콜백

siblings1
number

현재 페이지 양쪽에 표시할 페이지 수

boundaries1
number

시작/끝에 항상 표시할 페이지 수

size"default"
"xs" | "sm" | "default" | "lg" | "xl"

컴포넌트 사이즈 (28/32/36/40/48px)

variant"default"
"default" | "outline" | "ghost"

시각적 variant

color"default"
"default" | "primary"

활성 페이지 색상

radius"md"
"sm" | "base" | "md" | "lg" | "xl" | "full"

테두리 radius

disabledfalse
boolean

모든 조작 비활성화

withControlstrue
boolean

이전/다음 버튼 표시

withEdgesfalse
boolean

첫/마지막 이동 버튼 표시

loopfalse
boolean

마지막 페이지에서 첫 페이지로 순환

Pagination.Link

pageundefined
number

이동할 페이지 번호

isActiveauto
boolean

활성 상태 (생략 시 Context에서 자동 판단)

Pagination.Previous / Pagination.Next / Pagination.First / Pagination.Last

iconBuilt-in SVG icon
ReactNode

커스텀 아이콘

Anatomy

1
2
3
Prev
4
1
7
…
4
5
5
6
…
10
6
Next
Height36px
Min widthmin-w-9
Gapgap-1
Iconicon-sm
1
Root
nav 컨테이너
2
Content
플렉스 리스트
3
Prev / Next
이전/다음 버튼
4
Page Item
페이지 번호
5
Active Page
현재 페이지
6
Ellipsis
생략 기호

Best Practices

✓

권장

  • ✓데이터 양이 많을 때 페이지네이션을 사용합니다
  • ✓현재 페이지 위치를 명확하게 표시합니다
  • ✓siblings, boundaries로 적절한 페이지 범위를 설정합니다
  • ✓페이지가 많은 경우 withEdges로 첫/마지막 이동 버튼을 제공합니다
✕

지양

  • ✗데이터가 적을 때는 페이지네이션을 사용하지 않습니다
  • ✗페이지 이동 시 스크롤 위치 초기화를 빠뜨리지 않습니다
  • ✗모든 페이지 번호를 한 번에 표시하지 않습니다
  • ✗무한 스크롤과 함께 사용하지 않습니다

Accessibility

키보드 조작

모든 페이지 버튼은 Tab 키로 포커스 이동이 가능하며, Enter 또는 Space 키로 선택합니다. disabled 상태에서는 포커스가 이동하지 않습니다.

ARIA / WCAG

  • role="navigation" nav 요소에 설정
  • aria-label="pagination" 내비게이션 영역 식별
  • aria-current="page" 현재 페이지에 설정
  • aria-label="Go to page N" 각 버튼에 설정
  • default 36px, lg 40px 이상 (WCAG 2.5.8 준수)
  • aria-hidden="true" Ellipsis에 설정