0
# rc-pagination
1

2
## Package Information
3

4
- **Package Name**: rc-pagination
5
- **Package Type**: npm
6
- **Language**: TypeScript
7
- **Installation**: `npm install rc-pagination`
8

9
## Core Imports
10

11
**ES6 Import:**
12
```typescript
13
import Pagination from 'rc-pagination';
14
import type { PaginationProps, PaginationLocale } from 'rc-pagination';
15

16
// CSS import (required for styling)
17
import 'rc-pagination/assets/index.css';
18
```
19

20
**CommonJS Require:**
21
```javascript
22
const Pagination = require('rc-pagination');
23
// or
24
const { default: Pagination } = require('rc-pagination');
25
```
26

27
## Basic Usage
28

29
```typescript
30
import React, { useState } from 'react';
31
import Pagination from 'rc-pagination';
32
import 'rc-pagination/assets/index.css';
33

34
function App() {
35
  const [current, setCurrent] = useState(1);
36
  const [pageSize, setPageSize] = useState(10);
37

38
  return (
39
    <Pagination
40
      current={current}
41
      total={500}
42
      pageSize={pageSize}
43
      onChange={(page, size) => {
44
        setCurrent(page);
45
        setPageSize(size);
46
      }}
47
      showSizeChanger
48
      showQuickJumper
49
      showTotal={(total, range) => 
50
        `${range[0]}-${range[1]} of ${total} items`
51
      }
52
    />
53
  );
54
}
55
```
56

57
## Architecture
58

59
The rc-pagination package provides a comprehensive React pagination component with the following key architectural elements:
60

61
- **Main Pagination Component**: The primary `Pagination` component that orchestrates all pagination functionality
62
- **Internal Pager Components**: Individual page button components for consistent styling and behavior
63
- **Options Components**: Size changer and quick jumper controls for enhanced user interaction
64
- **Internationalization System**: 60+ built-in locales with full customization support
65
- **TypeScript Support**: Complete type definitions for all props, callbacks, and customization options
66

67
## Core Capabilities
68

69
### [Pagination Component](./pagination.md)
70
Complete pagination component with page navigation, size changing, and customizable display options.
71

72
```typescript { .api }
73
interface PaginationProps {
74
  // Core pagination
75
  current?: number;
76
  defaultCurrent?: number;
77
  total?: number;
78
  pageSize?: number;
79
  defaultPageSize?: number;
80
  onChange?: (page: number, pageSize: number) => void;
81
  onShowSizeChange?: (current: number, size: number) => void;
82
  
83
  // Display options
84
  hideOnSinglePage?: boolean;
85
  showSizeChanger?: boolean;
86
  showQuickJumper?: boolean | object;
87
  showTotal?: (total: number, range: [number, number]) => React.ReactNode;
88
  simple?: boolean | { readOnly?: boolean };
89
  
90
  // Missing critical props
91
  selectPrefixCls?: string;
92
  totalBoundaryShowSizeChanger?: number;
93
  sizeChangerRender?: SizeChangerRender;
94
  
95
  // Styling and layout
96
  className?: string;
97
  style?: React.CSSProperties;
98
  align?: 'start' | 'center' | 'end';
99
  disabled?: boolean;
100
}
101
```
102

103
### [Internationalization](./internationalization.md)
104
Complete localization support with 60+ built-in locales and customizable locale configuration.
105

106
```typescript { .api }
107
interface PaginationLocale {
108
  items_per_page?: string;
109
  jump_to?: string;
110
  jump_to_confirm?: string;
111
  page?: string;
112
  prev_page?: string;
113
  next_page?: string;
114
  prev_5?: string;
115
  next_5?: string;
116
  prev_3?: string;
117
  next_3?: string;
118
  page_size?: string;
119
}
120
```
121

122
### [Advanced Customization](./advanced-customization.md)
123
Advanced features including custom renderers, icons, size options, and accessibility support.
124

125
```typescript { .api }
126
// Advanced customization options available in PaginationProps
127
interface PaginationAdvancedFeatures {
128
  // Custom renderers
129
  itemRender?: (page: number, type: 'page' | 'prev' | 'next' | 'jump-prev' | 'jump-next', element: React.ReactNode) => React.ReactNode;
130
  sizeChangerRender?: (info: {
131
    disabled: boolean;
132
    size: number;
133
    onSizeChange: (value: string | number) => void;
134
    'aria-label': string;
135
    className: string;
136
    options: { label: string; value: string | number; }[];
137
  }) => React.ReactNode;
138
  
139
  // Icons customization  
140
  prevIcon?: React.ComponentType | React.ReactNode;
141
  nextIcon?: React.ComponentType | React.ReactNode;
142
  jumpPrevIcon?: React.ComponentType | React.ReactNode;
143
  jumpNextIcon?: React.ComponentType | React.ReactNode;
144
  
145
  // Size options
146
  pageSizeOptions?: number[];
147
  totalBoundaryShowSizeChanger?: number;
148
  
149
  // Advanced display
150
  showLessItems?: boolean;
151
  showPrevNextJumpers?: boolean;
152
  showTitle?: boolean;
153
}
154
```
155

156
## Common Patterns
157

158
### Controlled Pagination
159
```typescript
160
const [currentPage, setCurrentPage] = useState(1);
161
const [pageSize, setPageSize] = useState(20);
162

163
<Pagination
164
  current={currentPage}
165
  pageSize={pageSize}
166
  total={1000}
167
  onChange={(page, size) => {
168
    setCurrentPage(page);
169
    setPageSize(size);
170
  }}
171
/>
172
```
173

174
### Uncontrolled Pagination  
175
```typescript
176
<Pagination
177
  defaultCurrent={1}
178
  defaultPageSize={10}
179
  total={500}
180
  onChange={(page, pageSize) => {
181
    // Handle page change
182
    fetchData(page, pageSize);
183
  }}
184
/>
185
```
186

187
### Simple Mode
188
```typescript
189
<Pagination
190
  current={current}
191
  total={100}
192
  simple
193
  onChange={onChange}
194
/>
195
```
196

197
### Custom Total Display
198
```typescript
199
<Pagination
200
  current={current}
201
  total={1000}
202
  pageSize={20}
203
  showTotal={(total, range) => 
204
    `Showing ${range[0]} to ${range[1]} of ${total} entries`
205
  }
206
  onChange={onChange}
207
/>
208
```
209

210
## TypeScript Integration
211

212
The package provides complete TypeScript support with exported types:
213

214
```typescript { .api }
215
// Main component props (exported types)
216
export interface PaginationProps extends React.AriaAttributes {
217
  // Core pagination
218
  current?: number;
219
  defaultCurrent?: number;
220
  total?: number;
221
  pageSize?: number;
222
  defaultPageSize?: number;
223
  
224
  // Event handlers
225
  onChange?: (page: number, pageSize: number) => void;
226
  onShowSizeChange?: (current: number, size: number) => void;
227
  
228
  // Customization
229
  itemRender?: (page: number, type: 'page' | 'prev' | 'next' | 'jump-prev' | 'jump-next', element: React.ReactNode) => React.ReactNode;
230
  showTotal?: (total: number, range: [number, number]) => React.ReactNode;
231
  
232
  // Display and styling options
233
  hideOnSinglePage?: boolean;
234
  showSizeChanger?: boolean;
235
  showQuickJumper?: boolean | object;
236
  className?: string;
237
  style?: React.CSSProperties;
238
  align?: 'start' | 'center' | 'end';
239
  disabled?: boolean;
240
  
241
  // Additional configuration
242
  selectPrefixCls?: string;
243
  totalBoundaryShowSizeChanger?: number;
244
  sizeChangerRender?: SizeChangerRender;
245
  
246
  // Accessibility
247
  role?: React.AriaRole | undefined;
248
  
249
  // ... and many more options (see detailed docs)
250
}
251

252
// Size changer custom renderer type
253
export type SizeChangerRender = (info: {
254
  disabled: boolean;
255
  size: number;
256
  onSizeChange: (value: string | number) => void;
257
  'aria-label': string;
258
  className: string;
259
  options: {
260
    label: string;
261
    value: string | number;
262
  }[];
263
}) => React.ReactNode;
264

265
// Locale configuration
266
export interface PaginationLocale {
267
  items_per_page?: string;
268
  jump_to?: string;
269
  jump_to_confirm?: string;
270
  page?: string;
271
  prev_page?: string;
272
  next_page?: string;
273
  prev_5?: string;
274
  next_5?: string;
275
  prev_3?: string;
276
  next_3?: string;
277
  page_size?: string;
278
}
279

280
// Additional interfaces (internal, not exported)
281
interface PaginationData {
282
  className: string;
283
  selectPrefixCls: string;
284
  prefixCls: string;
285
  pageSizeOptions: number[];
286
  current: number;
287
  defaultCurrent: number;
288
  total: number;
289
  totalBoundaryShowSizeChanger?: number;
290
  pageSize: number;
291
  defaultPageSize: number;
292
  hideOnSinglePage: boolean;
293
  align: 'start' | 'center' | 'end';
294
  showSizeChanger: boolean;
295
  sizeChangerRender?: SizeChangerRender;
296
  showLessItems: boolean;
297
  showPrevNextJumpers: boolean;
298
  showQuickJumper: boolean | object;
299
  showTitle: boolean;
300
  simple: boolean | { readOnly?: boolean };
301
  disabled: boolean;
302
  locale: PaginationLocale;
303
  style: React.CSSProperties;
304
  prevIcon: React.ComponentType | React.ReactNode;
305
  nextIcon: React.ComponentType | React.ReactNode;
306
  jumpPrevIcon: React.ComponentType | React.ReactNode;
307
  jumpNextIcon: React.ComponentType | React.ReactNode;
308
}
309

310
interface PaginationState {
311
  current: number;
312
  currentInputValue: number;
313
  pageSize: number;
314
}
315
```
316

317
## Defaults and Behaviors
318

319
Key default values and automatic behaviors:
320

321
- **Default page size**: 10
322
- **Default current page**: 1
323
- **Default locale**: Chinese (zh_CN)
324
- **Show size changer threshold**: When `total > 50` (configurable via `totalBoundaryShowSizeChanger`)
325
- **Show previous/next jumpers**: `true` by default
326
- **Show titles on hover**: `true` by default
327

328
## Browser and React Compatibility
329

330
- **React**: >=16.9.0 (peer dependency)
331
- **ReactDOM**: >=16.9.0 (peer dependency)
332
- **Browsers**: Modern browsers with ES5+ support
333
- **SSR**: Server-side rendering compatible
334
- **TypeScript**: Full type definitions included