Pagination

Navigation

여러 페이지로 나뉜 목록을 탐색하는 페이지네이션.

Usage

많은 항목을 페이지 단위로 나눠 이동

import

import { Pagination } from '@mildang/design-system/Pagination';

예제를 복사해 쓸 때 필요한 준비

• @mildang/styled-system 은 이 저장소에서 Panda 가 생성하는 산출물이다. 저장소 안에서는 turbo run ship 이후 쓸 수 있고, 패키지 소비자는 자기 Panda 산출물이나 다른 레이아웃 수단으로 바꿔야 한다.

API Reference

Pagination Props

Prop

Type

Default

count

필수

number

지정 안 함

pageSize

필수

number

지정 안 함

defaultPage

number

disabled

boolean

false

hideNextButton

boolean

false

hidePrevButton

boolean

false

onChange

(event: ChangeEvent<unknown>, page: number) => void

지정 안 함

page

number

지정 안 함

panda

SystemStyleObject

지정 안 함

siblingCount

number

size

"md" | "sm"

페이지 번호 줄임 규칙

이전·다음 화살표는 항상 컴포넌트 양 끝에 있고, 그 사이 페이지 번호 목록의 줄임(…) 여부와 위치는 전부 @zag-js/pagination(Ark UI가 감싼 상태 머신)이 계산한다 — 이 컴포넌트에 별도의 커스텀 규칙은 없다.

전체 페이지 수(totalPages = ⌈count / pageSize⌉)가 siblingCount * 2 + 5 이하면 줄임표 없이 모든 페이지 번호를 보여준다. 기본값(siblingCount=1)에서는 이 경계가 7이다 — "5~7 이하는 Compact, 8 이상은 Expanded" 처럼 범위가 아니라 정확히 7이 기준이다.
경계를 넘으면 현재 페이지 위치에 따라 앞쪽에만, 뒤쪽에만, 또는 양쪽에 …가 나타난다. 현재 페이지가 시작에 가까우면 뒤쪽에만, 끝에 가까우면 앞쪽에만, 중간이면 양쪽에 뜬다.
첫 페이지와 마지막 페이지는 줄임표가 있어도 항상 번호로 노출된다(boundaryCount=1로 고정 — PaginationProps에 노출되지 않는 값이라 조정할 수 없다).
siblingCount(기본 1, prop으로 조정 가능)는 현재 페이지 양옆에 몇 개씩 번호를 더 보여줄지 정한다 — 값을 올리면 줄임표가 나타나는 경계(위 7)도 함께 늘어난다.

기본 사용

page 와 onChange 로 현재 페이지를 직접 들고 있는 형태 — 목록을 페이지 단위로 넘길 때의 출발점입니다.

코드

Open in Playground

import { default as Pagination } from '@mildang/design-system/Pagination';
import { ComponentProps } from 'react';

const STORY_DEFAULT_ARGS = { ...({}), ...({
    count: 100,
    pageSize: 10,
    size: 'md',
  }) } as ComponentProps<typeof Pagination>;

const PaginationDemoExampleRender = (args: ComponentProps<typeof Pagination>) => <Pagination {...args} />;

export default function PaginationDemoExample(props: Partial<ComponentProps<typeof Pagination>>) {
  const mergedProps = { ...STORY_DEFAULT_ARGS, ...props } as ComponentProps<typeof Pagination>;
  return PaginationDemoExampleRender(mergedProps);
}

주변 페이지 수

현재 페이지 양옆에 보여줄 형제 수를 0과 2로 비교합니다. 페이지가 많을수록 줄임표가 함께 나타납니다.

코드

Open in Playground

import { ComponentProps } from 'react';
import { default as Pagination } from '@mildang/design-system/Pagination';
import { Grid } from '@mildang/styled-system/jsx';

const STORY_DEFAULT_ARGS = {
  count: 200,
  pageSize: 10,
  size: 'md',
  defaultPage: 5,
} as ComponentProps<typeof Pagination>;

const PaginationSiblingCountExampleRender = (args: ComponentProps<typeof Pagination>) => (
    <Grid gap="24px" flexDirection="column" alignItems="flex-start">
      {[0, 1, 2].map((siblingCount) => (
        <div key={siblingCount} style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
          <div style={{ fontSize: '14px', color: '#666', fontWeight: 500 }}>siblingCount: {siblingCount}</div>
          <Pagination {...args} siblingCount={siblingCount} />
        </div>
      ))}
    </Grid>
  );

export default function PaginationSiblingCountExample(props: Partial<ComponentProps<typeof Pagination>>) {
  const mergedProps = { ...STORY_DEFAULT_ARGS, ...props } as ComponentProps<typeof Pagination>;
  return PaginationSiblingCountExampleRender(mergedProps);
}

상태별 표시

상태	뜻	실제 구현
Inactive	일반 페이지 버튼	기본 텍스트 색(`neutral.text.base`)
Hover	이동 가능성을 보여주는 강조	배경 오버레이 + 텍스트 색 전환
Active	현재 페이지, 가장 높은 시각적 강조	현재 값과 같은 페이지에만 붙는 `selected` 배경·텍스트 색(CSS `:active`, 즉 누르는 순간이 아니다)
Disabled	이동할 수 없는 상태	이전/다음 화살표는 첫/마지막 페이지에서 자동으로 비활성화된다. `disabled` prop을 켜면 화살표뿐 아니라 페이지 번호 버튼까지 함께 비활성화된다

기본 사용

page 와 onChange 로 현재 페이지를 직접 들고 있는 형태 — 목록을 페이지 단위로 넘길 때의 출발점입니다.

코드

Open in Playground

import { default as Pagination } from '@mildang/design-system/Pagination';
import { ComponentProps } from 'react';

const STORY_DEFAULT_ARGS = { ...({}), ...({
    count: 100,
    pageSize: 10,
    size: 'md',
  }) } as ComponentProps<typeof Pagination>;

const PaginationDemoExampleRender = (args: ComponentProps<typeof Pagination>) => <Pagination {...args} />;

export default function PaginationDemoExample(props: Partial<ComponentProps<typeof Pagination>>) {
  const mergedProps = { ...STORY_DEFAULT_ARGS, ...props } as ComponentProps<typeof Pagination>;
  return PaginationDemoExampleRender(mergedProps);
}