0
# Rendering API
1

2
Page-level operations including rendering to canvas, viewport calculations, and visual transformations. Essential for displaying PDF content in web applications.
3

4
## Capabilities
5

6
### PDF Page Proxy
7

8
Interface for individual PDF pages providing rendering, text extraction, and annotation access.
9

10
```javascript { .api }
11
interface PDFPageProxy {
12
  /** Page number (1-indexed) */
13
  pageNumber: number;
14
  /** Page rotation in degrees */
15
  rotate: number;
16
  /** Page reference object */
17
  ref: RefProxy;
18
  /** User unit (typically 1.0) */
19
  userUnit: number;
20
  /** Page dimensions in points */
21
  view: number[];
22
  
23
  /**
24
   * Render page to canvas context
25
   * @param params - Rendering parameters
26
   * @returns Render task for controlling operation
27
   */
28
  render(params: RenderParameters): RenderTask;
29
  
30
  /**
31
   * Get page viewport for given parameters
32
   * @param params - Viewport parameters
33
   * @returns Viewport with dimensions and transforms
34
   */
35
  getViewport(params: GetViewportParameters): PageViewport;
36
  
37
  /**
38
   * Get page annotations
39
   * @param params - Annotation parameters
40
   * @returns Promise resolving to annotation array
41
   */
42
  getAnnotations(params?: GetAnnotationsParameters): Promise<any[]>;
43
  
44
  /**
45
   * Extract text content from page
46
   * @param params - Text extraction parameters
47
   * @returns Promise resolving to text content
48
   */
49
  getTextContent(params?: GetTextContentParameters): Promise<TextContent>;
50
  
51
  /**
52
   * Get operator list for advanced rendering
53
   * @param params - Operator list parameters
54
   * @returns Promise resolving to operation list
55
   */
56
  getOperatorList(params?: GetOperatorListParameters): Promise<any>;
57
  
58
  /**
59
   * Get page structure tree for accessibility
60
   * @returns Promise resolving to structure tree
61
   */
62
  getStructTree(): Promise<any>;
63
  
64
  /**
65
   * Get JavaScript actions for this page
66
   * @returns Promise resolving to actions object
67
   */
68
  getJSActions(): Promise<{ [name: string]: any }>;
69
  
70
  /**
71
   * Clean up page resources
72
   * @param resetStats - Reset page statistics
73
   */
74
  cleanup(resetStats?: boolean): void;
75
  
76
  /**
77
   * Get page statistics
78
   * @returns Statistics object
79
   */
80
  getStats(): any;
81
}
82
```
83

84
### Render Parameters
85

86
Configuration for page rendering operations.
87

88
```javascript { .api }
89
interface RenderParameters {
90
  /** Canvas 2D rendering context */
91
  canvasContext: CanvasRenderingContext2D;
92
  /** Page viewport defining dimensions and transforms */
93
  viewport: PageViewport;
94
  /** Rendering intent (default: "display") */
95
  intent?: "display" | "print" | "any";
96
  /** Enable WebGL acceleration */
97
  enableWebGL?: boolean;
98
  /** Render interactive form elements */
99
  renderInteractiveForms?: boolean;
100
  /** Additional transform matrix */
101
  transform?: number[];
102
  /** Background color */
103
  background?: string;
104
  /** Image layer for background images */
105
  imageLayer?: any;
106
  /** Canvas factory for creating additional canvases */
107
  canvasFactory?: any;
108
  /** Optional content configuration */
109
  optionalContentConfigPromise?: Promise<any>;
110
  /** Annotation canvas map */
111
  annotationCanvasMap?: Map<string, HTMLCanvasElement>;
112
  /** Page colors for forced color mode */
113
  pageColors?: any;
114
}
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
import { getDocument } from "pdfjs-dist";
121

122
// Load document and get page
123
const pdf = await getDocument("document.pdf").promise;
124
const page = await pdf.getPage(1);
125

126
// Set up canvas
127
const canvas = document.getElementById("pdf-canvas");
128
const context = canvas.getContext("2d");
129

130
// Get viewport and configure canvas
131
const viewport = page.getViewport({ scale: 1.5 });
132
canvas.width = viewport.width;
133
canvas.height = viewport.height;
134

135
// Render page
136
const renderContext = {
137
  canvasContext: context,
138
  viewport: viewport,
139
  intent: "display"
140
};
141

142
const renderTask = page.render(renderContext);
143
await renderTask.promise;
144
console.log("Page rendered successfully");
145
```
146

147
### Page Viewport
148

149
Represents page dimensions and coordinate transformations for rendering.
150

151
```javascript { .api }
152
class PageViewport {
153
  /** Viewport width in pixels */
154
  width: number;
155
  /** Viewport height in pixels */
156
  height: number;
157
  /** Scaling factor applied */
158
  scale: number;
159
  /** Rotation angle in degrees */
160
  rotation: number;
161
  /** Horizontal offset */
162
  offsetX: number;
163
  /** Vertical offset */
164
  offsetY: number;
165
  /** Transformation matrix */
166
  transform: number[];
167
  /** Raw dimensions from PDF */
168
  viewBox: number[];
169
  
170
  /**
171
   * Clone viewport with new parameters
172
   * @param params - Parameters to override
173
   * @returns New viewport instance
174
   */
175
  clone(params?: Partial<GetViewportParameters>): PageViewport;
176
  
177
  /**
178
   * Convert PDF coordinates to viewport coordinates
179
   * @param x - PDF X coordinate
180
   * @param y - PDF Y coordinate
181
   * @returns Viewport coordinates [x, y]
182
   */
183
  convertToViewportPoint(x: number, y: number): number[];
184
  
185
  /**
186
   * Convert viewport coordinates to PDF coordinates
187
   * @param x - Viewport X coordinate
188
   * @param y - Viewport Y coordinate
189
   * @returns PDF coordinates [x, y]
190
   */
191
  convertToPdfPoint(x: number, y: number): number[];
192
  
193
  /**
194
   * Convert PDF rectangle to viewport rectangle
195
   * @param rect - PDF rectangle [x1, y1, x2, y2]
196
   * @returns Viewport rectangle [x1, y1, x2, y2]
197
   */
198
  convertToViewportRectangle(rect: number[]): number[];
199
}
200
```
201

202
### Viewport Parameters
203

204
Configuration for creating page viewports.
205

206
```javascript { .api }
207
interface GetViewportParameters {
208
  /** Scaling factor (default: 1.0) */
209
  scale?: number;
210
  /** Rotation angle in degrees (0, 90, 180, 270) */
211
  rotation?: number;
212
  /** Horizontal offset in pixels */
213
  offsetX?: number;
214
  /** Vertical offset in pixels */
215
  offsetY?: number;
216
  /** Don't flip Y axis (default: false) */
217
  dontFlip?: boolean;
218
}
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
// Different viewport configurations
225
const viewport1 = page.getViewport({ scale: 1.0 });
226
const viewport2 = page.getViewport({ scale: 2.0, rotation: 90 });
227
const viewport3 = page.getViewport({ 
228
  scale: 1.5, 
229
  offsetX: 100, 
230
  offsetY: 50 
231
});
232

233
// Convert coordinates
234
const pdfPoint = [100, 200];
235
const viewportPoint = viewport1.convertToViewportPoint(pdfPoint[0], pdfPoint[1]);
236
console.log(`PDF ${pdfPoint} -> Viewport ${viewportPoint}`);
237

238
// Handle different page orientations
239
const isLandscape = viewport.width > viewport.height;
240
```
241

242
### Render Task
243

244
Controls an ongoing rendering operation with progress tracking and cancellation.
245

246
```javascript { .api }
247
interface RenderTask {
248
  /** Promise that resolves when rendering completes */
249
  promise: Promise<void>;
250
  
251
  /**
252
   * Cancel the rendering operation
253
   * @param extraDelay - Extra delay before cleanup
254
   */
255
  cancel(extraDelay?: number): void;
256
  
257
  /** Whether task is cancelled */
258
  cancelled: boolean;
259
  
260
  /** Rendering progress callback */
261
  onProgress?: (progressData: { percent: number }) => void;
262
  
263
  /** Continue rendering callback for chunked rendering */
264
  onContinue?: (cont: () => void) => void;
265
}
266
```
267

268
**Usage Examples:**
269

270
```javascript
271
// Render with progress tracking
272
const renderTask = page.render(renderContext);
273

274
renderTask.onProgress = (progress) => {
275
  console.log(`Rendering progress: ${progress.percent}%`);
276
};
277

278
try {
279
  await renderTask.promise;
280
  console.log("Rendering complete");
281
} catch (error) {
282
  if (renderTask.cancelled) {
283
    console.log("Rendering was cancelled");
284
  } else {
285
    console.error("Rendering failed:", error);
286
  }
287
}
288

289
// Cancel rendering if needed
290
if (shouldCancel) {
291
  renderTask.cancel();
292
}
293
```
294

295
### Annotation Parameters
296

297
Configuration for retrieving page annotations.
298

299
```javascript { .api }
300
interface GetAnnotationsParameters {
301
  /** Rendering intent */
302
  intent?: "display" | "print" | "any";
303
}
304
```
305

306
### Text Content Extraction
307

308
Parameters and interfaces for extracting text from PDF pages.
309

310
```javascript { .api }
311
interface GetTextContentParameters {
312
  /** Normalize whitespace */
313
  normalizeWhitespace?: boolean;
314
  /** Disable text combining */
315
  disableCombineTextItems?: boolean;
316
  /** Include marked content */
317
  includeMarkedContent?: boolean;
318
}
319

320
interface TextContent {
321
  /** Text items on the page */
322
  items: TextItem[];
323
  /** Text styles */
324
  styles: { [fontName: string]: TextStyle };
325
  /** Language information */
326
  lang?: string;
327
}
328

329
interface TextItem {
330
  /** Text string */
331
  str: string;
332
  /** Text direction */
333
  dir: "ltr" | "rtl" | "ttb";
334
  /** Text width */
335
  width: number;
336
  /** Text height */
337
  height: number;
338
  /** Text transform matrix */
339
  transform: number[];
340
  /** Font name */
341
  fontName: string;
342
  /** Whether text has end-of-line */
343
  hasEOL?: boolean;
344
}
345

346
interface TextStyle {
347
  /** Text ascent */
348
  ascent: number;
349
  /** Text descent */
350
  descent: number;
351
  /** Vertical alignment */
352
  vertical?: boolean;
353
  /** Font family */
354
  fontFamily: string;
355
}
356
```
357

358
**Usage Examples:**
359

360
```javascript
361
// Extract text content
362
const textContent = await page.getTextContent({
363
  normalizeWhitespace: true,
364
  disableCombineTextItems: false
365
});
366

367
// Process text items
368
let pageText = "";
369
textContent.items.forEach(item => {
370
  pageText += item.str;
371
  if (item.hasEOL) {
372
    pageText += "\n";
373
  }
374
});
375

376
console.log("Page text:", pageText);
377

378
// Access text positioning
379
textContent.items.forEach(item => {
380
  const [x, y] = item.transform.slice(4, 6);
381
  console.log(`Text "${item.str}" at position (${x}, ${y})`);
382
});
383
```
384

385
### Operator List Parameters
386

387
Configuration for retrieving low-level drawing operations.
388

389
```javascript { .api }
390
interface GetOperatorListParameters {
391
  /** Rendering intent */
392
  intent?: "display" | "print" | "any";
393
  /** Render interactive forms */
394
  renderInteractiveForms?: boolean;
395
  /** Transform matrix */
396
  transform?: number[];
397
  /** Optional content configuration */
398
  optionalContentConfigPromise?: Promise<any>;
399
}
400
```
401

402
### Display Utilities
403

404
Helper functions for rendering operations.
405

406
```javascript { .api }
407
/**
408
 * Calculate output scale for high-DPI displays
409
 * @param ctx - Canvas rendering context
410
 * @returns Scale factors for X and Y axes
411
 */
412
function getOutputScale(ctx: CanvasRenderingContext2D): { sx: number; sy: number };
413

414
/**
415
 * Set layer dimensions to match viewport
416
 * @param layer - HTML element to resize
417
 * @param viewport - Target viewport
418
 */
419
function setLayerDimensions(layer: HTMLElement, viewport: PageViewport): void;
420

421
/**
422
 * Check if URL uses data scheme
423
 * @param url - URL to check
424
 * @returns Whether URL is data scheme
425
 */
426
function isDataScheme(url: string): boolean;
427

428
/**
429
 * Check if file appears to be PDF
430
 * @param filename - Filename to check
431
 * @returns Whether file is likely PDF
432
 */
433
function isPdfFile(filename: string): boolean;
434
```
435

436
**Usage Examples:**
437

438
```javascript
439
import { getOutputScale, setLayerDimensions } from "pdfjs-dist";
440

441
// Handle high-DPI displays
442
const outputScale = getOutputScale(context);
443
if (outputScale.sx !== 1 || outputScale.sy !== 1) {
444
  canvas.width = Math.floor(viewport.width * outputScale.sx);
445
  canvas.height = Math.floor(viewport.height * outputScale.sy);
446
  context.scale(outputScale.sx, outputScale.sy);
447
}
448

449
// Set up text layer
450
const textLayer = document.getElementById("text-layer");
451
setLayerDimensions(textLayer, viewport);
452
```