0
# Pagination Component
1
2
The `Pagination` component provides comprehensive pagination functionality for React applications, supporting both controlled and uncontrolled modes with extensive customization options.
3
4
## Import
5
6
```typescript
7
import Pagination from 'rc-pagination';
8
import type { PaginationProps } from 'rc-pagination';
9
import 'rc-pagination/assets/index.css';
10
```
11
12
## Complete API
13
14
```typescript { .api }
15
/**
16
* Main pagination component props interface
17
* Extends React ARIA attributes for accessibility
18
*/
19
interface PaginationProps extends React.AriaAttributes {
20
// Core pagination control
21
current?: number;
22
defaultCurrent?: number;
23
total?: number;
24
pageSize?: number;
25
defaultPageSize?: number;
26
27
// Event handlers
28
onChange?: (page: number, pageSize: number) => void;
29
onShowSizeChange?: (current: number, size: number) => void;
30
31
// Display options
32
hideOnSinglePage?: boolean;
33
showSizeChanger?: boolean;
34
showQuickJumper?: boolean | object;
35
showTotal?: (total: number, range: [number, number]) => React.ReactNode;
36
showLessItems?: boolean;
37
showPrevNextJumpers?: boolean;
38
showTitle?: boolean;
39
simple?: boolean | { readOnly?: boolean };
40
41
// Styling and layout
42
className?: string;
43
style?: React.CSSProperties;
44
prefixCls?: string;
45
selectPrefixCls?: string;
46
align?: 'start' | 'center' | 'end';
47
disabled?: boolean;
48
49
// Icons
50
prevIcon?: React.ComponentType | React.ReactNode;
51
nextIcon?: React.ComponentType | React.ReactNode;
52
jumpPrevIcon?: React.ComponentType | React.ReactNode;
53
jumpNextIcon?: React.ComponentType | React.ReactNode;
54
55
// Size options
56
pageSizeOptions?: number[];
57
totalBoundaryShowSizeChanger?: number;
58
59
// Customization
60
itemRender?: (page: number, type: 'page' | 'prev' | 'next' | 'jump-prev' | 'jump-next', element: React.ReactNode) => React.ReactNode;
61
sizeChangerRender?: (info: SizeChangerRenderInfo) => React.ReactNode;
62
buildOptionText?: (value: number | string) => string;
63
64
// Internationalization
65
locale?: PaginationLocale;
66
67
// Accessibility
68
role?: React.AriaRole | undefined;
69
}
70
71
/**
72
* Size changer render function parameters
73
*/
74
interface SizeChangerRenderInfo {
75
disabled: boolean; // Whether the size changer is disabled
76
size: number; // Current page size
77
onSizeChange: (value: string | number) => void; // Handler for size changes
78
'aria-label': string; // ARIA label for accessibility
79
className: string; // CSS class name
80
options: { // Available size options
81
label: string; // Display label for the option
82
value: string | number; // Value for the option
83
}[];
84
}
85
```
86
87
## Core Pagination Properties
88
89
### Page Control
90
91
**current** (number, optional)
92
Current active page number. When provided, the component operates in controlled mode.
93
94
**defaultCurrent** (number, optional, default: 1)
95
Initial page number for uncontrolled mode.
96
97
**total** (number, optional, default: 0)
98
Total number of items across all pages.
99
100
**pageSize** (number, optional)
101
Number of items per page. When provided, the component operates in controlled mode.
102
103
**defaultPageSize** (number, optional, default: 10)
104
Initial page size for uncontrolled mode.
105
106
### Event Handlers
107
108
**onChange** (function, optional)
109
Callback fired when the page number or page size changes.
110
```typescript
111
(page: number, pageSize: number) => void
112
```
113
114
**onShowSizeChange** (function, optional)
115
Callback fired when the page size changes via the size changer.
116
```typescript
117
(current: number, size: number) => void
118
```
119
120
## Display Configuration
121
122
### Visibility Options
123
124
**hideOnSinglePage** (boolean, optional, default: false)
125
Hide the pagination component when there is only one page.
126
127
**showSizeChanger** (boolean, optional)
128
Show the page size selector. Can be boolean or an object with select component options.
129
- `false`: Never show size changer
130
- `true`: Always show size changer
131
- Auto: Shows when total > `totalBoundaryShowSizeChanger` (default 50)
132
133
**showQuickJumper** (boolean | object, optional, default: false)
134
Show the quick page jumper input.
135
- `true`: Show basic quick jumper
136
- `{ goButton: true }`: Show with go button
137
- `{ goButton: 'Go' }`: Show with custom go button text
138
139
**showTotal** (function, optional)
140
Custom function to display total information.
141
```typescript
142
(total: number, range: [number, number]) => React.ReactNode
143
```
144
145
**showLessItems** (boolean, optional, default: false)
146
Show fewer page number buttons to save space.
147
148
**showPrevNextJumpers** (boolean, optional, default: true)
149
Show the jump-previous and jump-next buttons (... buttons).
150
151
**showTitle** (boolean, optional, default: true)
152
Show title attributes on page buttons for accessibility.
153
154
### Layout and Styling
155
156
**align** ('start' | 'center' | 'end', optional)
157
Horizontal alignment of pagination component.
158
159
**className** (string, optional)
160
Custom CSS class name for the pagination wrapper.
161
162
**style** (React.CSSProperties, optional)
163
Inline styles for the pagination wrapper.
164
165
**prefixCls** (string, optional, default: 'rc-pagination')
166
CSS class prefix for pagination elements.
167
168
**selectPrefixCls** (string, optional, default: 'rc-select')
169
CSS class prefix for the size selector component.
170
171
**disabled** (boolean, optional, default: false)
172
Disable the entire pagination component.
173
174
## Usage Examples
175
176
### Basic Controlled Pagination
177
178
```typescript
179
import React, { useState } from 'react';
180
import Pagination from 'rc-pagination';
181
182
function DataTable() {
183
const [current, setCurrent] = useState(1);
184
const [pageSize, setPageSize] = useState(10);
185
const totalItems = 500;
186
187
const handleChange = (page: number, size: number) => {
188
setCurrent(page);
189
setPageSize(size);
190
// Fetch data for the new page
191
fetchData(page, size);
192
};
193
194
return (
195
<div>
196
{/* Your data display */}
197
<Pagination
198
current={current}
199
pageSize={pageSize}
200
total={totalItems}
201
onChange={handleChange}
202
showSizeChanger
203
showQuickJumper
204
showTotal={(total, range) =>
205
`${range[0]}-${range[1]} of ${total} items`
206
}
207
/>
208
</div>
209
);
210
}
211
```
212
213
### Uncontrolled Pagination
214
215
```typescript
216
function SimpleList() {
217
const handlePageChange = (page: number, pageSize: number) => {
218
console.log(`Page ${page}, Size ${pageSize}`);
219
// Handle page change without state management
220
loadPageData(page, pageSize);
221
};
222
223
return (
224
<Pagination
225
defaultCurrent={1}
226
defaultPageSize={20}
227
total={1000}
228
onChange={handlePageChange}
229
hideOnSinglePage
230
/>
231
);
232
}
233
```
234
235
### Simple Mode
236
237
```typescript
238
function MobilePagination() {
239
const [current, setCurrent] = useState(1);
240
241
return (
242
<Pagination
243
current={current}
244
total={100}
245
pageSize={10}
246
simple
247
onChange={(page) => setCurrent(page)}
248
/>
249
);
250
}
251
```
252
253
### Custom Total Display
254
255
```typescript
256
function CustomTotalPagination() {
257
return (
258
<Pagination
259
current={1}
260
total={1500}
261
pageSize={25}
262
showTotal={(total, range) => (
263
<span>
264
Showing <strong>{range[0]}</strong> to <strong>{range[1]}</strong> of{' '}
265
<strong>{total}</strong> results
266
</span>
267
)}
268
onChange={(page, pageSize) => {
269
// Handle change
270
}}
271
/>
272
);
273
}
274
```
275
276
### With Custom Page Size Options
277
278
```typescript
279
function CustomSizeOptions() {
280
return (
281
<Pagination
282
current={1}
283
total={1000}
284
pageSize={20}
285
pageSizeOptions={[10, 20, 50, 100, 200]}
286
showSizeChanger
287
onChange={(page, pageSize) => {
288
// Handle change
289
}}
290
onShowSizeChange={(current, size) => {
291
console.log(`Current page: ${current}, New size: ${size}`);
292
}}
293
/>
294
);
295
}
296
```
297
298
### Aligned Pagination
299
300
```typescript
301
function AlignedPagination() {
302
return (
303
<div>
304
{/* Center aligned */}
305
<Pagination
306
current={1}
307
total={100}
308
align="center"
309
onChange={() => {}}
310
/>
311
312
{/* Right aligned */}
313
<Pagination
314
current={1}
315
total={100}
316
align="end"
317
onChange={() => {}}
318
/>
319
</div>
320
);
321
}
322
```
323
324
### Disabled State
325
326
```typescript
327
function DisabledPagination() {
328
return (
329
<Pagination
330
current={5}
331
total={100}
332
disabled
333
onChange={() => {}}
334
/>
335
);
336
}
337
```
338
339
## Advanced Features
340
341
### Auto Size Changer Display
342
343
The `totalBoundaryShowSizeChanger` property (default: 50) automatically shows or hides the size changer based on the total number of items:
344
345
```typescript
346
<Pagination
347
current={1}
348
total={25} // Size changer hidden (< 50)
349
totalBoundaryShowSizeChanger={30}
350
onChange={() => {}}
351
/>
352
353
<Pagination
354
current={1}
355
total={100} // Size changer shown (>= 50)
356
onChange={() => {}}
357
/>
358
```
359
360
### Responsive Behavior
361
362
Use `showLessItems` for compact display on smaller screens:
363
364
```typescript
365
const isMobile = window.innerWidth < 768;
366
367
<Pagination
368
current={current}
369
total={1000}
370
showLessItems={isMobile}
371
onChange={onChange}
372
/>
373
```
374
375
## Accessibility
376
377
The component includes built-in accessibility features:
378
379
- ARIA attributes for screen readers
380
- Keyboard navigation support
381
- Semantic HTML structure
382
- Configurable `role` attribute
383
- Title attributes for page buttons (controllable via `showTitle`)
384
385
```typescript
386
<Pagination
387
current={1}
388
total={100}
389
role="navigation"
390
aria-label="Data table pagination"
391
showTitle={true}
392
onChange={() => {}}
393
/>
394
```