페이지네이션
페이지네이션 (Pagination)
많은 데이터를 페이지 단위로 나눠 탐색할 수 있게 해 주는 컴포넌트예요. 목록을 모두 렌더링하기 부담스러울 때 데이터를 페이지로 나눠 보여 줘요.
출처: 문서
본문
언제 사용하나요 (When To Use)
- 모든 항목을 로드하거나 렌더링하는 데 오랜 시간이 걸릴 때 사용해요.
- 페이지를 넘겨가며 데이터를 탐색하고 싶을 때 사용해요.
예시 (Examples)
기본 (Basic)
기본 페이지네이션이에요.
import React from 'react';
import { Pagination } from 'antd';
const App: React.FC = () => <Pagination defaultCurrent={1} total={50} />;
export default App;
정렬 (Align)
import React from 'react';
import { Pagination } from 'antd';
const App: React.FC = () => (
<>
<Pagination align="start" defaultCurrent={1} total={50} />
<br />
<Pagination align="center" defaultCurrent={1} total={50} />
<br />
<Pagination align="end" defaultCurrent={1} total={50} />
</>
);
export default App;
더 보기 (More)
페이지가 더 많을 때예요.
import React from 'react';
import { Pagination } from 'antd';
const App: React.FC = () => <Pagination defaultCurrent={6} total={500} />;
export default App;
크기 변경 (Changer)
pageSize를 변경해요.
import React from 'react';
import type { PaginationProps } from 'antd';
import { Pagination } from 'antd';
const onShowSizeChange: PaginationProps['onShowSizeChange'] = (current, pageSize) => {
console.log(current, pageSize);
};
const App: React.FC = () => (
<>
<Pagination
showSizeChanger
onShowSizeChange={onShowSizeChange}
defaultCurrent={3}
total={500}
/>
<br />
<Pagination
showSizeChanger
onShowSizeChange={onShowSizeChange}
defaultCurrent={3}
total={500}
disabled
/>
</>
);
export default App;
점프 (Jumper)
원하는 페이지로 바로 점프해요.
import React from 'react';
import type { PaginationProps } from 'antd';
import { Pagination } from 'antd';
const onChange: PaginationProps['onChange'] = (pageNumber) => {
console.log('Page: ', pageNumber);
};
const App: React.FC = () => (
<>
<Pagination showQuickJumper defaultCurrent={2} total={500} onChange={onChange} />
<br />
<Pagination showQuickJumper defaultCurrent={2} total={500} onChange={onChange} disabled />
</>
);
export default App;
크기 (Size)
작은 크기와 큰 크기의 페이지네이션이에요.
import React from 'react';
import type { PaginationProps } from 'antd';
import { Divider, Flex, Pagination } from 'antd';
const showTotal: PaginationProps['showTotal'] = (total) => `Total ${total} items`;
const App: React.FC = () => (
<Flex vertical gap="medium">
<Divider titlePlacement="start">Small</Divider>
<Pagination size="small" total={50} />
<Pagination size="small" total={50} showSizeChanger showQuickJumper />
<Pagination size="small" total={50} showTotal={showTotal} />
<Pagination
size="small"
total={50}
disabled
showTotal={showTotal}
showSizeChanger
showQuickJumper
/>
<Divider titlePlacement="start">Large</Divider>
<Pagination size="large" total={50} />
<Pagination size="large" total={50} showSizeChanger showQuickJumper />
<Pagination size="large" total={50} showTotal={showTotal} />
<Pagination
size="large"
total={50}
disabled
showTotal={showTotal}
showSizeChanger
showQuickJumper
/>
</Flex>
);
export default App;
단순 모드 (Simple mode)
단순 모드예요.
import React from 'react';
import { Pagination } from 'antd';
const App: React.FC = () => (
<>
<Pagination simple defaultCurrent={2} total={50} />
<br />
<Pagination simple={{ readOnly: true }} defaultCurrent={2} total={50} />
<br />
<Pagination disabled simple defaultCurrent={2} total={50} />
</>
);
export default App;
제어 (Controlled)
페이지 번호를 제어해요.
import React, { useState } from 'react';
import type { PaginationProps } from 'antd';
import { Pagination } from 'antd';
const App: React.FC = () => {
const [current, setCurrent] = useState(3);
const onChange: PaginationProps['onChange'] = (page) => {
console.log(page);
setCurrent(page);
};
return <Pagination current={current} onChange={onChange} total={50} />;
};
export default App;
전체 수 (Total number)
showTotal을 설정하면 데이터의 전체 수를 보여 줄 수 있어요.
import React from 'react';
import { Pagination } from 'antd';
const App: React.FC = () => (
<>
<Pagination
total={85}
showTotal={(total) => `Total ${total} items`}
defaultPageSize={20}
defaultCurrent={1}
/>
<br />
<Pagination
total={85}
showTotal={(total, range) => `${range[0]}-${range[1]} of ${total} items`}
defaultPageSize={20}
defaultCurrent={1}
/>
</>
);
export default App;
모두 표시 (Show All)
설정한 모든 prop을 보여 줘요.
import React from 'react';
import { Pagination } from 'antd';
const App: React.FC = () => (
<Pagination
total={85}
showSizeChanger
showQuickJumper
showTotal={(total) => `Total ${total} items`}
/>
);
export default App;
이전/다음 (Prev and next)
이전·다음 버튼에 텍스트 링크를 사용해요.
import React from 'react';
import type { PaginationProps } from 'antd';
import { Pagination } from 'antd';
const itemRender: PaginationProps['itemRender'] = (_, type, originalElement) => {
if (type === 'prev') {
return <a>Previous</a>;
}
if (type === 'next') {
return <a>Next</a>;
}
return originalElement;
};
const App: React.FC = () => <Pagination total={500} itemRender={itemRender} />;
export default App;
커스텀 컴포넌트 (Custom component)
components로 페이지 크기 변경기를 교체해요.
import React from 'react';
import type { PaginationProps } from 'antd';
import { InputNumber, Pagination } from 'antd';
type SizeChangerComponent = Required<NonNullable<PaginationProps['components']>>['sizeChanger'];
type GetProps<T> = T extends React.ComponentType<infer P> ? P : never;
const SizeChanger = (props: GetProps<SizeChangerComponent>) => {
const { disabled, value, onChange, className } = props;
return (
<InputNumber
aria-label="Page Size"
className={className}
disabled={disabled}
min={1}
precision={0}
style={{ width: 100 }}
value={value}
onChange={(nextValue) => {
if (nextValue !== null) {
onChange(nextValue);
}
}}
/>
);
};
const App: React.FC = () => (
<Pagination
showSizeChanger
components={{
sizeChanger: SizeChanger,
}}
defaultCurrent={3}
total={500}
/>
);
export default App;
시맨틱 DOM 스타일링 (Custom semantic dom styling)
classNames와 styles로 객체나 함수를 전달해 Pagination의 시맨틱 DOM 스타일을 커스터마이즈할 수 있어요.
import React from 'react';
import { Flex, Pagination } from 'antd';
import type { GetProp, PaginationProps } from 'antd';
import { createStaticStyles } from 'antd-style';
const classNames = createStaticStyles(({ css }) => ({
root: css`
border: 2px dashed #ccc;
padding: 8px;
`,
}));
const styleFn: PaginationProps['styles'] = ({
props,
}): GetProp<PaginationProps, 'styles', 'Return'> => {
if (props.size === 'small') {
return {
item: {
backgroundColor: `rgba(200, 200, 200, 0.3)`,
marginInlineEnd: 4,
},
};
}
return {};
};
const App: React.FC = () => {
const paginationSharedProps: PaginationProps = {
total: 500,
classNames: { root: classNames.root },
};
return (
<Flex vertical gap="medium">
<Pagination {...paginationSharedProps} styles={{ item: { borderRadius: 999 } }} />
<Pagination {...paginationSharedProps} size="small" styles={styleFn} />
</Flex>
);
};
export default App;
API
공통 props는 Common props를 참고해요.
<Pagination onChange={onChange} total={50} />
| 속성 (Property) | 설명 (Description) | 타입 (Type) | 기본값 (Default) | 버전 (Version) | 글로벌 설정 |
|---|---|---|---|---|---|
| align | 정렬 | start | center | end | - | 5.19.0 | × |
| classNames | 컴포넌트 내부의 각 시맨틱 구조에 대한 class를 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string> | - | 6.0.0 | |
| components | 내부 컴포넌트 커스터마이즈 | { sizeChanger?: React.ComponentType } | - | 6.6.0 | × |
| current | 현재 페이지 번호 | number | - | × | |
| defaultCurrent | 기본 초기 페이지 번호 | number | 1 | × | |
| defaultPageSize | 페이지당 기본 데이터 항목 수 | number | 10 | × | |
| disabled | 페이지네이션 비활성화 | boolean | - | × | |
| hideOnSinglePage | 단일 페이지일 때 페이저를 숨길지 여부 | boolean | false | × | |
| itemRender | 항목의 innerHTML을 커스터마이즈 | (page, type: 'page' | 'prev' | 'next', originalElement) => React.ReactNode | - | × | |
| pageSize | 페이지당 데이터 항목 수 | number | - | × | |
| pageSizeOptions | sizeChanger 옵션 지정 | number[] | [10, 20, 50, 100] |
× | |
| responsive | size를 지정하지 않으면 창 너비에 따라 Pagination이 크기를 조정해요. |
boolean | - | × | |
| showLessItems | 더 적은 페이지 항목 표시 | boolean | false | × | |
| showQuickJumper | 페이지로 직접 점프할 수 있는지 여부 | boolean | { goButton: ReactNode } | false | × | |
| showSizeChanger | pageSize 선택을 표시할지 여부 |
boolean | SelectProps | - | SelectProps: 5.21.0 | 4.21.0, SelectProps: 5.21.0 |
| showTitle | 페이지 항목의 title 표시 | boolean | true | × | |
| showTotal | 전체 수와 범위를 표시 | function(total, range) | - | × | |
| simple | 단순 모드 사용 여부 | boolean | { readOnly?: boolean } | - | × | |
| size | 컴포넌트 크기 | large | medium | small |
medium |
× | |
| styles | 컴포넌트 내부의 각 시맨틱 구조에 대한 인라인 스타일을 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties> | - | 6.0.0 | |
| total | 데이터 항목의 전체 수 | number | 0 | × | |
| totalBoundaryShowSizeChanger | total이 이 값보다 크면 showSizeChanger가 true가 돼요. |
number | 50 | 6.2.0 | |
| onChange | 페이지 번호나 pageSize가 변경될 때 호출돼요. 결과 페이지 번호와 pageSize를 인자로 받아요. |
function(page, pageSize) | - | × | |
| onShowSizeChange | pageSize가 변경될 때 호출돼요. |
function(current, size) | - | × |
시맨틱 DOM (Semantic DOM)
시맨틱 DOM 구조는 https://ant.design/components/pagination/semantic.md 에서 확인할 수 있어요.
디자인 토큰 (Design Token)
컴포넌트 토큰 (Pagination) (Component Token)
| 토큰 이름 (Token Name) | 설명 (Description) | 타입 (Type) | 기본값 (Default Value) |
|---|---|---|---|
| itemActiveBg | 활성 Pagination 항목의 배경색 | string | #ffffff |
| itemActiveBgDisabled | 비활성 활성 Pagination 항목의 배경색 | string | rgba(0,0,0,0.15) |
| itemActiveColor | 활성 Pagination 항목의 텍스트 색 | string | #1677ff |
| itemActiveColorDisabled | 비활성 활성 Pagination 항목의 텍스트 색 | string | rgba(0,0,0,0.25) |
| itemActiveColorHover | 활성 Pagination 항목 hover 시 텍스트 색 | string | #4096ff |
| itemBg | Pagination 항목의 배경색 | string | #ffffff |
| itemInputBg | 입력 상자의 배경색 | string | #ffffff |
| itemLinkBg | Pagination 항목 링크의 배경색 | string | #ffffff |
| itemSize | Pagination 항목 크기 | number | 32 |
| itemSizeLG | 큰 Pagination 항목 크기 | number | 40 |
| itemSizeSM | 작은 Pagination 항목 크기 | number | 24 |
| miniOptionsSizeChangerTop | Pagination 크기 변경기의 Top | number | 0 |
글로벌 토큰 (Global Token)
| 토큰 이름 (Token Name) | 설명 (Description) | 타입 (Type) | 기본값 (Default Value) |
|---|---|---|---|
| borderRadius | 기본 컴포넌트의 테두리 반경 | number | |
| borderRadiusLG | LG 크기 테두리 반경이에요. Card, Modal 등 큰 테두리 반경을 가진 컴포넌트에 사용돼요. | number | |
| borderRadiusSM | SM 크기 테두리 반경이에요. Button, Input, Select 등 작은 크기의 입력 컴포넌트에 사용돼요. | number | |
| colorBgContainer | 컨테이너 배경색이에요. 기본 버튼, 입력 상자 등. colorBgElevated와 혼동하지 마세요. |
string | |
| colorBgContainerDisabled | 비활성 상태에서 컨테이너의 배경색을 제어해요. | string | |
| colorBgTextActive | 활성 상태에서 텍스트의 배경색을 제어해요. | string | |
| colorBgTextHover | hover 상태에서 텍스트의 배경색을 제어해요. | string | |
| colorBorder | 기본 테두리 색이에요. 폼 구분선, 카드 구분선처럼 서로 다른 요소를 구분하는 데 사용돼요. | string | |
| colorBorderDisabled | 비활성 상태의 요소 테두리 색을 제어해요. | string | |
| colorFillSecondary | 2단계 fill 색으로 Rate, Skeleton 등 요소의 모양을 더 선명하게 나타낼 수 있어요. Table 등에서 3단계 fill 색의 Hover 상태로도 쓰여요. | string | |
| colorFillTertiary | 3단계 fill 색으로 Slider, Segmented 등 요소의 모양을 나타내는 데 사용돼요. 강조 요구가 없다면 3단계 fill 색을 기본 fill로 쓰는 걸 권장해요. | string | |
| colorPrimary | 브랜드 색은 제품의 특성과 커뮤니케이션을 반영하는 가장 직접적인 시각 요소 중 하나예요. 브랜드 색을 선택하면 자동으로 완전한 색 팔레트가 생성되고 유효한 디자인 시맨틱이 부여돼요. | string | |
| colorPrimaryBorder | 메인 색 그라데이션 아래의 스트로크 색이에요. Slider 같은 컴포넌트의 stroke에 사용돼요. | string | |
| colorPrimaryHover | 메인 색 그라데이션 아래의 Hover 상태 | string | |
| colorText | W3C 표준을 따르는 기본 텍스트 색이에요. 가장 어두운 중성색이기도 해요. | string | |
| colorTextDisabled | 비활성 상태의 텍스트 색을 제어해요. | string | |
| colorTextPlaceholder | 플레이스홀더 텍스트 색을 제어해요. | string | |
| controlHeightLG | LG 컴포넌트 높이 | number | |
| controlOutline | 입력 컴포넌트의 outline 색을 제어해요. | string | |
| controlOutlineWidth | 입력 컴포넌트의 outline 너비를 제어해요. | number | |
| fontFamily | Ant Design의 글꼴은 시스템의 기본 인터페이스 글꼴을 우선시하고, 화면 표시에 적합한 대체 글꼴 라이브러리를 제공해 플랫폼과 브라우저에 따라 가독성을 유지하며 친근하고 안정적이며 전문적인 특성을 반영해요. | string | |
| fontSize | 디자인 시스템에서 가장 널리 쓰이는 글자 크기로, 여기서 텍스트 그라데이션이 파생돼요. | number | |
| fontSizeSM | 작은 글자 크기 | number | |
| fontWeightStrong | 제목 컴포넌트(h1, h2, h3 등)나 선택된 항목의 글자 굵기를 제어해요. | number | |
| lineHeight | 텍스트의 줄 높이예요. | number | |
| lineHeightLG | 큰 텍스트의 줄 높이예요. | number | |
| lineType | 기본 컴포넌트의 테두리 스타일 | string | |
| lineWidth | 기본 컴포넌트의 테두리 두께 | number | |
| margin | 중간 크기의 요소 여백을 제어해요. | number | |
| marginSM | 중간-작은 크기의 요소 여백을 제어해요. | number | |
| marginXS | 작은 크기의 요소 여백을 제어해요. | number | |
| marginXXS | 가장 작은 크기의 요소 여백을 제어해요. | number | |
| motionDurationMid | 동작 속도, 중간 속도예요. 중간 요소의 애니메이션 상호작용에 사용돼요. | string | |
| paddingXXS | 요소의 아주 작은 패딩을 제어해요. | number | |
| screenLG | 큰 화면의 화면 너비를 제어해요. | number | |
| screenSM | 작은 화면의 화면 너비를 제어해요. | number | |
| sizeLG | 큰 크기 | number |