Pagination#

대용량 콘텐츠를 페이지 단위로 나누어 탐색할 수 있는 컴포넌트입니다. 현재 페이지 표시, 이전/다음 이동, 첫/마지막 페이지 이동을 지원합니다.

Live Preview#

class PaginationDefaultExample extends StatefulComponent {
  const PaginationDefaultExample({super.key});

  @override
  State<PaginationDefaultExample> createState() =>
      _PaginationDefaultExampleState();
}

class _PaginationDefaultExampleState extends State<PaginationDefaultExample> {
  int _page = 3;

  @override
  Component build(BuildContext context) {
    return Pagination(
      page: _page,
      totalPages: 10,
      onPageChanged: (value) => setState(() => _page = value),
    );
  }
}

class PaginationDefaultExample extends StatefulWidget {
  const PaginationDefaultExample({super.key});

  @override
  State<PaginationDefaultExample> createState() =>
      _PaginationDefaultExampleState();
}

class _PaginationDefaultExampleState extends State<PaginationDefaultExample> {
  int _page = 3;

  @override
  Widget build(BuildContext context) {
    return Pagination(
      page: _page,
      totalPages: 10,
      onPageChanged: (p) => setState(() => _page = p),
    );
  }
}

class PaginationChainExample extends StatefulComponent {
  const PaginationChainExample({super.key});

  @override
  State<PaginationChainExample> createState() => _PaginationChainExampleState();
}

class _PaginationChainExampleState extends State<PaginationChainExample> {
  int _page = 3;

  @override
  Component build(BuildContext context) {
    return Pagination(
      page: _page,
      totalPages: 10,
      onPageChanged: (value) => setState(() => _page = value),
    ).withStyle(
      const CorePaginationStyle(
        itemSpacing: CoreSpace.space8,
        buttonSize: CoreSize.size40,
        buttonRadius: CoreBorderRadius.all(CoreRadius.radius16),
        activeBackgroundColor: CoreColor.token(CoreColors.tertiary),
      ),
    );
  }
}

class PaginationChainExample extends StatefulWidget {
  const PaginationChainExample({super.key});

  @override
  State<PaginationChainExample> createState() => _PaginationChainExampleState();
}

class _PaginationChainExampleState extends State<PaginationChainExample> {
  int _page = 3;

  @override
  Widget build(BuildContext context) {
    return Pagination(
      page: _page,
      totalPages: 10,
      onPageChanged: (p) => setState(() => _page = p),
    ).withStyle(
      const CorePaginationStyle(
        itemSpacing: CoreSpace.space8,
        buttonSize: CoreSize.size40,
        buttonRadius: CoreBorderRadius.all(CoreRadius.radius16),
        activeBackgroundColor: CoreColor.token(CoreColors.tertiary),
      ),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 테이블, 검색 결과, 상품 목록처럼 많은 데이터를 페이지 단위로 나눠 표시할 때
• 사용자가 특정 페이지로 직접 이동할 수 있어야 할 때
• 전체 데이터 양이 많지 않아 페이지 번호로 탐색이 유용한 경우

대신 다른 컴포넌트를 사용하세요:

• RefreshTrigger: 무한 스크롤 방식으로 데이터를 로드할 때
• Select: 페이지 크기 선택 등 드롭다운 옵션이 필요할 때

기본 사용법 (Basic Usage)#

Flutter / Web 모두 동일한 Pagination API 를 사용합니다.

// 기본 페이지네이션
Pagination(
  page: _currentPage,
  totalPages: 10,
  onPageChanged: handlePageChanged,
)

// 더 넓은 페이지 범위 + prev/next 라벨
Pagination(
  page: _currentPage,
  totalPages: 20,
  onPageChanged: handlePageChanged,
  maxPages: 7,
  showLabel: true,
)

// 첫 페이지에서 이전 버튼 숨김
Pagination(
  page: _currentPage,
  totalPages: 5,
  onPageChanged: handlePageChanged,
  hidePreviousOnFirstPage: true,
)

// 기본 페이지네이션 (이전/다음 버튼 포함)
Pagination(
  page: currentPage,
  totalPages: 10,
  onPageChanged: handlePageChanged,
)

// 더 넓은 페이지 범위 + prev/next 라벨
Pagination(
  page: currentPage,
  totalPages: 20,
  onPageChanged: handlePageChanged,
  maxPages: 7,
  showLabel: true,
)

Props / Parameters#

스타일 시스템 (Style System)#

Pagination 의 모든 chrome / dimensional 오버라이드는 CorePaginationStyle 단일 슬롯으로 흐릅니다. behaviour 필드 (page / totalPages / onPageChanged / maxPages / showSkipToFirstPage / showSkipToLastPage / hidePreviousOnFirstPage / hideNextOnLastPage / showLabel) 는 위젯/컴포넌트 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 / behaviour: 위젯/컴포넌트 파라미터로 직접 (page, totalPages, onPageChanged, maxPages, showSkipToFirstPage, showSkipToLastPage, hidePreviousOnFirstPage, hideNextOnLastPage, showLabel)
• chrome / dimensional: CorePaginationStyle 한 곳으로

Resolve chain#

CorePaginationStyle.defaultX                   // design system default
  → CorePaginationTheme.style                  // 프로젝트 공통
  → widget.paginationStyle                     // 인스턴스별

CorePaginationStyle 필드#

빠른 오버라이드 (Chain)#

이미 만든 Pagination 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

class PaginationChainExample extends StatefulWidget {
  const PaginationChainExample({super.key});

  @override
  State<PaginationChainExample> createState() => _PaginationChainExampleState();
}

class _PaginationChainExampleState extends State<PaginationChainExample> {
  int _page = 3;

  @override
  Widget build(BuildContext context) {
    return Pagination(
      page: _page,
      totalPages: 10,
      onPageChanged: (p) => setState(() => _page = p),
    ).withStyle(
      const CorePaginationStyle(
        itemSpacing: CoreSpace.space8,
        buttonSize: CoreSize.size40,
        buttonRadius: CoreBorderRadius.all(CoreRadius.radius16),
        activeBackgroundColor: CoreColor.token(CoreColors.tertiary),
      ),
    );
  }
}

class PaginationChainExample extends StatefulComponent {
  const PaginationChainExample({super.key});

  @override
  State<PaginationChainExample> createState() => _PaginationChainExampleState();
}

class _PaginationChainExampleState extends State<PaginationChainExample> {
  int _page = 3;

  @override
  Component build(BuildContext context) {
    return Pagination(
      page: _page,
      totalPages: 10,
      onPageChanged: (value) => setState(() => _page = value),
    ).withStyle(
      const CorePaginationStyle(
        itemSpacing: CoreSpace.space8,
        buttonSize: CoreSize.size40,
        buttonRadius: CoreBorderRadius.all(CoreRadius.radius16),
        activeBackgroundColor: CoreColor.token(CoreColors.tertiary),
      ),
    );
  }
}

변형 (Variants)#

Pagination 은 현재 단일 시각 변형(standard) 을 가집니다. 표시되는 페이지 범위와 prev/next 라벨은 behaviour 파라미터로 조정합니다.

// 더 넓은 페이지 범위 + 라벨
Pagination(
  page: 5,
  totalPages: 20,
  onPageChanged: handlePageChanged,
  maxPages: 7,
  showLabel: true,
)

동작 스펙 (Behavior)#

인터랙션#

• 페이지 버튼 클릭: 해당 페이지로 이동 (onPageChanged(page) 호출)
• 이전/다음 버튼: 현재 페이지에서 1씩 감소/증가
• 첫/마지막 버튼: 1페이지 또는 totalPages로 이동
• 현재 페이지 버튼: 클릭해도 이벤트 없음 (비활성 강조)
• 경계 버튼: 첫 페이지에서 이전 버튼, 마지막 페이지에서 다음 버튼은 비활성

상태 전환#

• 현재 페이지 버튼: 강조 색상 + 비활성 클릭
• 경계 도달 시 이전/다음 버튼 disabled 처리
• 페이지 수가 많으면 현재 페이지 기준으로 중간 항목 ...으로 생략

애니메이션#

• 페이지 전환 시 별도 애니메이션 없음 (콘텐츠 영역 전환은 부모가 처리)
• 버튼 호버 시 배경색 200ms 전환

사용 가이드라인 (Usage Guidelines)#

✅ Do#

Pagination(
  page: _currentPage,
  totalPages: 50,
  onPageChanged: handlePageChanged,
  showSkipToFirstPage: true,
  showSkipToLastPage: true,
)

❌ Don't#

// ❌ 페이지가 1개뿐인데 Pagination 표시
Pagination(
  page: 1,
  totalPages: 1,
  onPageChanged: handlePageChanged,
)

✅ Do#

Pagination(
  page: _currentPage,
  totalPages: 20,
  onPageChanged: handlePageChanged,
  maxPages: 3,
)

❌ Don't#

// ❌ 한 페이지에 다 들어오는데도 표시
Pagination(
  page: 1,
  totalPages: 1,
  onPageChanged: handlePageChanged,
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: Semantics(label: '페이지 3, 전체 10페이지') 형태로 현재/전체 페이지 전달
• Web: role="navigation" + aria-label="페이지 탐색" + 현재 페이지에 aria-current="page" 적용

터치 타겟#

• 각 페이지 버튼 최소 히트 영역: 24×24 논리 픽셀 (WCAG 2.2 AA, CoreTouchTarget.minimum) — 보이는 크기를 유지한 채 히트 영역만 넓힙니다

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Table: 페이지네이션이 필요한 대용량 테이블 데이터에 사용
• Select: 페이지 크기 선택 드롭다운과 조합