0
# Page Rendering
1

2
Page rendering system with multiple layer support and extensive customization options for displaying individual PDF pages with text selection, annotations, and forms.
3

4
## Capabilities
5

6
### Page Component
7

8
Renders individual PDF pages with multiple layers and comprehensive customization options.
9

10
```typescript { .api }
11
/**
12
 * Displays a PDF page with configurable layers and rendering options
13
 * Should be placed inside <Document /> or passed explicit pdf prop
14
 * @param props - Page configuration and event handlers
15
 * @returns React element rendering the PDF page
16
 */
17
function Page(props: PageProps): React.ReactElement;
18

19
interface PageProps {
20
  /** Which page to display by page number (1-based) */
21
  pageNumber?: number;
22
  /** Which page to display by page index (0-based) */
23
  pageIndex?: number;
24
  /** Page scale factor */
25
  scale?: number;
26
  /** Page rotation in degrees (90, 180, 270) */
27
  rotate?: number | null;
28
  /** Fixed width in pixels (overrides scale if both provided) */
29
  width?: number;
30
  /** Fixed height in pixels (overrides scale if both provided) */
31
  height?: number;
32
  /** Rendering mode for the page */
33
  renderMode?: RenderMode;
34
  /** Whether to render text layer for selection and accessibility */
35
  renderTextLayer?: boolean;
36
  /** Whether to render annotations (links, forms, etc.) */
37
  renderAnnotationLayer?: boolean;
38
  /** Whether to render interactive forms */
39
  renderForms?: boolean;
40
  /** Custom renderer component for 'custom' render mode */
41
  customRenderer?: CustomRenderer;
42
  /** Custom text renderer function */
43
  customTextRenderer?: CustomTextRenderer;
44
  /** Device pixel ratio for high DPI displays */
45
  devicePixelRatio?: number;
46
  /** Canvas background color */
47
  canvasBackground?: string;
48
  /** Function called when page loads successfully */
49
  onLoadSuccess?: (page: PageCallback) => void;
50
  /** Function called when page fails to load */
51
  onLoadError?: (error: Error) => void;
52
  /** Function called when page renders successfully */
53
  onRenderSuccess?: () => void;
54
  /** Function called when page fails to render */
55
  onRenderError?: (error: Error) => void;
56
  /** Function called when text layer renders successfully */
57
  onRenderTextLayerSuccess?: () => void;
58
  /** Function called when text layer fails to render */
59
  onRenderTextLayerError?: (error: Error) => void;
60
  /** Function called when annotation layer renders successfully */
61
  onRenderAnnotationLayerSuccess?: () => void;
62
  /** Function called when annotation layer fails to render */
63
  onRenderAnnotationLayerError?: (error: unknown) => void;
64
  /** Function called when text content is loaded successfully */
65
  onGetTextSuccess?: (textContent: TextContent) => void;
66
  /** Function called when text content fails to load */
67
  onGetTextError?: (error: Error) => void;
68
  /** Function called when annotations are loaded successfully */
69
  onGetAnnotationsSuccess?: (annotations: Annotations) => void;
70
  /** Function called when annotations fail to load */
71
  onGetAnnotationsError?: (error: Error) => void;
72
  /** Child components or render function */
73
  children?: React.ReactNode | ((props: PageRenderProps) => React.ReactNode);
74
  /** Class names for styling */
75
  className?: ClassName;
76
  /** Custom error message or component */
77
  error?: NodeOrRenderer;
78
  /** Custom loading message or component */
79
  loading?: NodeOrRenderer;
80
  /** Custom no-data message or component */
81
  noData?: NodeOrRenderer;
82
  /** React ref for the main page div */
83
  inputRef?: React.Ref<HTMLDivElement | null>;
84
  /** React ref for the canvas element */
85
  canvasRef?: React.Ref<HTMLCanvasElement>;
86
}
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { Document, Page } from "react-pdf";
93

94
// Basic page rendering
95
function BasicPageViewer() {
96
  return (
97
    <Document file="sample.pdf">
98
      <Page pageNumber={1} />
99
    </Document>
100
  );
101
}
102

103
// Page with custom size and layers
104
function CustomPageViewer() {
105
  return (
106
    <Document file="sample.pdf">
107
      <Page
108
        pageNumber={1}
109
        width={600}
110
        renderTextLayer={true}
111
        renderAnnotationLayer={true}
112
        renderForms={true}
113
        onLoadSuccess={(page) => {
114
          console.log('Page loaded:', page.width, 'x', page.height);
115
        }}
116
        onRenderSuccess={() => {
117
          console.log('Page rendered successfully');
118
        }}
119
      />
120
    </Document>
121
  );
122
}
123

124
// Multiple pages with different configurations
125
function MultiPageViewer() {
126
  const [numPages, setNumPages] = useState(null);
127
  
128
  return (
129
    <Document 
130
      file="sample.pdf"
131
      onLoadSuccess={({ numPages }) => setNumPages(numPages)}
132
    >
133
      {Array.from({ length: numPages }, (_, index) => (
134
        <Page
135
          key={`page_${index + 1}`}
136
          pageNumber={index + 1}
137
          scale={0.8}
138
          renderTextLayer={false}
139
          className="pdf-page"
140
        />
141
      ))}
142
    </Document>
143
  );
144
}
145
```
146

147
### Render Modes
148

149
Different rendering modes for various use cases and performance requirements.
150

151
```typescript { .api }
152
type RenderMode = 'canvas' | 'custom' | 'none';
153

154
type CustomRenderer = React.FunctionComponent | React.ComponentClass;
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
// Canvas mode (default) - renders to HTML5 canvas
161
<Page pageNumber={1} renderMode="canvas" />
162

163
// Custom renderer mode - use your own rendering component
164
function MyCustomRenderer() {
165
  const pageContext = usePageContext();
166
  // Custom rendering logic using page context
167
  return <div>Custom rendered page</div>;
168
}
169

170
<Page 
171
  pageNumber={1} 
172
  renderMode="custom" 
173
  customRenderer={MyCustomRenderer} 
174
/>
175

176
// None mode - no visual rendering, useful for text extraction
177
<Page pageNumber={1} renderMode="none" />
178
```
179

180
### Page Sizing and Scaling
181

182
Flexible sizing options with automatic scaling and fixed dimensions.
183

184
```typescript { .api }
185
interface PageSizingProps {
186
  /** Page scale factor (default: 1) */
187
  scale?: number;
188
  /** Fixed width in pixels */
189
  width?: number;
190
  /** Fixed height in pixels */
191
  height?: number;
192
  /** Page rotation in degrees */
193
  rotate?: number | null;
194
  /** Device pixel ratio for high DPI displays */
195
  devicePixelRatio?: number;
196
}
197
```
198

199
**Usage Examples:**
200

201
```typescript
202
// Scale-based sizing
203
<Page pageNumber={1} scale={1.5} /> // 150% size
204
<Page pageNumber={1} scale={0.5} /> // 50% size
205

206
// Fixed width (height calculated automatically)
207
<Page pageNumber={1} width={800} />
208

209
// Fixed height (width calculated automatically)  
210
<Page pageNumber={1} height={600} />
211

212
// Rotation
213
<Page pageNumber={1} rotate={90} />  // 90 degrees clockwise
214
<Page pageNumber={1} rotate={180} /> // upside down
215
<Page pageNumber={1} rotate={270} /> // 90 degrees counter-clockwise
216

217
// High DPI displays
218
<Page pageNumber={1} devicePixelRatio={2} />
219
```
220

221
### Text Layer
222

223
Text layer rendering for text selection, search, and accessibility.
224

225
```typescript { .api }
226
interface TextLayerProps {
227
  /** Whether to render text layer */
228
  renderTextLayer?: boolean;
229
  /** Custom text renderer function */
230
  customTextRenderer?: CustomTextRenderer;
231
  /** Function called when text content loads successfully */
232
  onGetTextSuccess?: (textContent: TextContent) => void;
233
  /** Function called when text content fails to load */
234
  onGetTextError?: (error: Error) => void;
235
  /** Function called when text layer renders successfully */
236
  onRenderTextLayerSuccess?: () => void;
237
  /** Function called when text layer fails to render */
238
  onRenderTextLayerError?: (error: Error) => void;
239
}
240

241
type CustomTextRenderer = (
242
  props: { pageIndex: number; pageNumber: number; itemIndex: number } & TextItem
243
) => string;
244

245
interface TextContent {
246
  items: (TextItem | TextMarkedContent)[];
247
  styles: Record<string, TextStyle>;
248
}
249

250
interface TextItem {
251
  str: string;
252
  dir: string;
253
  width: number;
254
  height: number;
255
  transform: number[];
256
  fontName: string;
257
}
258
```
259

260
**Usage Examples:**
261

262
```typescript
263
// Basic text layer
264
<Page pageNumber={1} renderTextLayer={true} />
265

266
// Custom text highlighting
267
function highlightSearchTerms(props) {
268
  const { str } = props;
269
  return str.replace(/search-term/gi, '<mark>$&</mark>');
270
}
271

272
<Page 
273
  pageNumber={1} 
274
  renderTextLayer={true}
275
  customTextRenderer={highlightSearchTerms}
276
/>
277

278
// Text extraction
279
function TextExtractor() {
280
  const [text, setText] = useState('');
281
  
282
  return (
283
    <Page
284
      pageNumber={1}
285
      renderMode="none"
286
      onGetTextSuccess={(textContent) => {
287
        const pageText = textContent.items
288
          .filter(item => 'str' in item)
289
          .map(item => item.str)
290
          .join(' ');
291
        setText(pageText);
292
      }}
293
    />
294
  );
295
}
296
```
297

298
### Annotation Layer
299

300
Annotation layer rendering for interactive links, forms, and other PDF annotations.
301

302
```typescript { .api }
303
interface AnnotationLayerProps {
304
  /** Whether to render annotation layer */
305
  renderAnnotationLayer?: boolean;
306
  /** Whether to render interactive forms */
307
  renderForms?: boolean;
308
  /** Function called when annotations load successfully */
309
  onGetAnnotationsSuccess?: (annotations: Annotations) => void;
310
  /** Function called when annotations fail to load */
311
  onGetAnnotationsError?: (error: Error) => void;
312
  /** Function called when annotation layer renders successfully */
313
  onRenderAnnotationLayerSuccess?: () => void;
314
  /** Function called when annotation layer fails to render */
315
  onRenderAnnotationLayerError?: (error: unknown) => void;
316
}
317

318
type Annotations = AnnotationData[];
319

320
interface AnnotationData {
321
  annotationType: number;
322
  color?: number[];
323
  dest?: Dest;
324
  url?: string;
325
  rect: number[];
326
  subtype: string;
327
}
328
```
329

330
**Usage Examples:**
331

332
```typescript
333
// Basic annotations (links, etc.)
334
<Page 
335
  pageNumber={1} 
336
  renderAnnotationLayer={true} 
337
/>
338

339
// Annotations with forms
340
<Page 
341
  pageNumber={1} 
342
  renderAnnotationLayer={true}
343
  renderForms={true}
344
  onGetAnnotationsSuccess={(annotations) => {
345
    console.log('Found', annotations.length, 'annotations');
346
  }}
347
/>
348

349
// Handle annotation clicks via Document
350
<Document 
351
  file="sample.pdf"
352
  onItemClick={({ pageNumber, dest }) => {
353
    console.log('Clicked annotation leading to page', pageNumber);
354
  }}
355
>
356
  <Page pageNumber={1} renderAnnotationLayer={true} />
357
</Document>
358
```
359

360
### Event Handlers
361

362
Comprehensive event system for page lifecycle and rendering states.
363

364
```typescript { .api }
365
interface PageCallback extends PDFPageProxy {
366
  /** Rendered page width in pixels */
367
  width: number;
368
  /** Rendered page height in pixels */
369
  height: number;
370
  /** Original page width from PDF */
371
  originalWidth: number;
372
  /** Original page height from PDF */
373
  originalHeight: number;
374
}
375

376
type OnPageLoadSuccess = (page: PageCallback) => void;
377
type OnPageLoadError = (error: Error) => void;
378
type OnRenderSuccess = () => void;
379
type OnRenderError = (error: Error) => void;
380
type OnGetTextSuccess = (textContent: TextContent) => void;
381
type OnGetTextError = (error: Error) => void;
382
type OnGetAnnotationsSuccess = (annotations: Annotations) => void;
383
type OnGetAnnotationsError = (error: Error) => void;
384
```
385

386
### Page Context
387

388
Page context data available to child components and custom renderers.
389

390
```typescript { .api }
391
interface PageRenderProps {
392
  /** PDF page proxy object */
393
  page: PDFPageProxy;
394
  /** Zero-based page index */
395
  pageIndex: number;
396
  /** One-based page number */
397
  pageNumber: number;
398
  /** Page scale factor */
399
  scale: number;
400
  /** Page rotation in degrees */
401
  rotate: number;
402
  /** Canvas background color */
403
  canvasBackground?: string;
404
  /** Custom text renderer function */
405
  customTextRenderer?: CustomTextRenderer;
406
  /** Device pixel ratio */
407
  devicePixelRatio?: number;
408
  /** Whether forms should be rendered */
409
  renderForms: boolean;
410
  /** Whether text layer should be rendered */
411
  renderTextLayer: boolean;
412
}
413
```
414

415
### Advanced Styling
416

417
Canvas customization and CSS styling options for page appearance.
418

419
```typescript { .api }
420
interface PageStylingProps {
421
  /** Canvas background color (any valid CSS color) */
422
  canvasBackground?: string;
423
  /** Class names for the page container */
424
  className?: ClassName;
425
  /** React ref for the page container div */
426
  inputRef?: React.Ref<HTMLDivElement | null>;
427
  /** React ref for the canvas element */
428
  canvasRef?: React.Ref<HTMLCanvasElement>;
429
}
430
```
431

432
**Usage Examples:**
433

434
```typescript
435
// Custom canvas background
436
<Page 
437
  pageNumber={1} 
438
  canvasBackground="transparent" 
439
/>
440

441
// CSS styling
442
<Page 
443
  pageNumber={1} 
444
  className="custom-page shadow-lg border-2"
445
  style={{ margin: '20px' }}
446
/>
447

448
// Canvas reference for custom operations
449
function CanvasEditor() {
450
  const canvasRef = useRef(null);
451
  
452
  const addWatermark = () => {
453
    const canvas = canvasRef.current;
454
    const ctx = canvas.getContext('2d');
455
    ctx.fillStyle = 'rgba(255, 0, 0, 0.3)';
456
    ctx.fillText('CONFIDENTIAL', 50, 50);
457
  };
458
  
459
  return (
460
    <Page 
461
      pageNumber={1}
462
      canvasRef={canvasRef}
463
      onRenderSuccess={addWatermark}
464
    />
465
  );
466
}
467
```