0
# React-PDF
1

2
React-PDF is a React component library for displaying PDF documents in React applications with the same ease as displaying images. It provides a comprehensive set of components including Document, Page, Outline, and Thumbnail that leverage PDF.js for robust PDF rendering capabilities.
3

4
## Package Information
5

6
- **Package Name**: react-pdf
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-pdf`
10

11
## Core Imports
12

13
```typescript
14
import { Document, Page, Outline, Thumbnail, pdfjs } from "react-pdf";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Document, Page, Outline, Thumbnail, pdfjs } = require("react-pdf");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { Document, Page, pdfjs } from "react-pdf";
27

28
// Configure PDF.js worker (required)
29
pdfjs.GlobalWorkerOptions.workerSrc = new URL(
30
  'pdfjs-dist/build/pdf.worker.min.mjs',
31
  import.meta.url,
32
).toString();
33

34
function MyPDFViewer() {
35
  const [numPages, setNumPages] = useState(null);
36
  const [pageNumber, setPageNumber] = useState(1);
37

38
  function onDocumentLoadSuccess({ numPages }) {
39
    setNumPages(numPages);
40
  }
41

42
  return (
43
    <div>
44
      <Document
45
        file="https://example.com/sample.pdf"
46
        onLoadSuccess={onDocumentLoadSuccess}
47
      >
48
        <Page pageNumber={pageNumber} />
49
      </Document>
50
      <p>
51
        Page {pageNumber} of {numPages}
52
      </p>
53
    </div>
54
  );
55
}
56
```
57

58
## Architecture
59

60
React-PDF is built around several key components:
61

62
- **Document Component**: Main container that loads and manages PDF documents, handles loading states, password protection, and provides context to child components
63
- **Page Component**: Renders individual PDF pages with multiple layers (canvas, text, annotations) and supports various rendering modes and customization options
64
- **Context System**: React context-based data flow using DocumentContext and PageContext for sharing PDF state and configuration between components
65
- **Layer System**: Modular rendering layers (Canvas, TextLayer, AnnotationLayer) that can be independently enabled/disabled for performance and functionality control
66
- **Event System**: Comprehensive callback system for handling document loading, page rendering, user interactions, and error states
67
- **PDF.js Integration**: Direct integration with Mozilla's PDF.js library for reliable PDF parsing and rendering across browsers
68

69
## Capabilities
70

71
### PDF.js Integration
72

73
Direct integration with Mozilla's PDF.js library for PDF processing, worker configuration, and advanced PDF operations.
74

75
```typescript { .api }
76
import { pdfjs } from "react-pdf";
77

78
// PDF.js library object for worker configuration and advanced operations
79
const pdfjs: typeof import('pdfjs-dist');
80

81
interface GlobalWorkerOptions {
82
  workerSrc: string;
83
}
84

85
// Configure PDF.js worker (required for functionality)
86
pdfjs.GlobalWorkerOptions.workerSrc = string;
87

88
// Access to full PDF.js API for advanced operations
89
pdfjs.getDocument(src: DocumentInitParameters): PDFDocumentLoadingTask;
90
```
91

92
### Document Management
93

94
Document loading and management functionality for handling PDF files from various sources with comprehensive loading states and error handling.
95

96
```typescript { .api }
97
function Document(props: DocumentProps): React.ReactElement;
98

99
interface DocumentProps {
100
  file?: File;
101
  onLoadSuccess?: (document: PDFDocumentProxy) => void;
102
  onLoadError?: (error: Error) => void;
103
  onLoadProgress?: (args: { loaded: number; total: number }) => void;
104
  onPassword?: (callback: (password: string | null) => void, reason: PasswordResponse) => void;
105
  children?: React.ReactNode | ((props: DocumentRenderProps) => React.ReactNode);
106
}
107

108
type File = string | ArrayBuffer | Blob | Source | null;
109

110
interface Source {
111
  data?: BinaryData;
112
  url?: string;
113
  range?: PDFDataRangeTransport;
114
}
115
```
116

117
[Document Management](./document-management.md)
118

119
### Page Rendering
120

121
Page rendering system with multiple layer support and extensive customization options for displaying individual PDF pages.
122

123
```typescript { .api }
124
function Page(props: PageProps): React.ReactElement;
125

126
interface PageProps {
127
  pageNumber?: number;
128
  pageIndex?: number;
129
  scale?: number;
130
  rotate?: number | null;
131
  width?: number;
132
  height?: number;
133
  renderMode?: RenderMode;
134
  renderTextLayer?: boolean;
135
  renderAnnotationLayer?: boolean;
136
  renderForms?: boolean;
137
  onLoadSuccess?: (page: PageCallback) => void;
138
  onLoadError?: (error: Error) => void;
139
}
140

141
type RenderMode = 'canvas' | 'custom' | 'none';
142

143
interface PageCallback extends PDFPageProxy {
144
  width: number;
145
  height: number;
146
  originalWidth: number;
147
  originalHeight: number;
148
}
149
```
150

151
[Page Rendering](./page-rendering.md)
152

153
### Navigation Components
154

155
Navigation components for PDF outline (table of contents) and thumbnail displays to enhance user experience.
156

157
```typescript { .api }
158
function Outline(props: OutlineProps): React.ReactElement | null;
159
function Thumbnail(props: ThumbnailProps): React.ReactElement;
160

161
interface OutlineProps {
162
  onItemClick?: (args: OnItemClickArgs) => void;
163
  onLoadSuccess?: (outline: PDFOutline) => void;
164
  onLoadError?: (error: Error) => void;
165
}
166

167
interface OnItemClickArgs {
168
  dest?: Dest;
169
  pageIndex: number;
170
  pageNumber: number;
171
}
172
```
173

174
[Navigation Components](./navigation-components.md)
175

176
### Context Hooks
177

178
React hooks for accessing PDF context data and state within component trees.
179

180
```typescript { .api }
181
function useDocumentContext(): DocumentContextType;
182
function usePageContext(): PageContextType;
183
function useOutlineContext(): OutlineContextType;
184

185
interface DocumentContextType {
186
  imageResourcesPath?: ImageResourcesPath;
187
  linkService: LinkService;
188
  onItemClick?: (args: OnItemClickArgs) => void;
189
  pdf?: PDFDocumentProxy | false;
190
  registerPage: RegisterPage;
191
  renderMode?: RenderMode;
192
  rotate?: number | null;
193
  unregisterPage: UnregisterPage;
194
}
195

196
interface PageContextType {
197
  _className?: string;
198
  canvasBackground?: string;
199
  customTextRenderer?: CustomTextRenderer;
200
  devicePixelRatio?: number;
201
  onGetAnnotationsError?: OnGetAnnotationsError;
202
  onGetAnnotationsSuccess?: OnGetAnnotationsSuccess;
203
  onGetStructTreeError?: OnGetStructTreeError;
204
  onGetStructTreeSuccess?: OnGetStructTreeSuccess;
205
  onGetTextError?: OnGetTextError;
206
  onGetTextSuccess?: OnGetTextSuccess;
207
  onRenderAnnotationLayerError?: OnRenderAnnotationLayerError;
208
  onRenderAnnotationLayerSuccess?: OnRenderAnnotationLayerSuccess;
209
  onRenderError?: OnRenderError;
210
  onRenderSuccess?: OnRenderSuccess;
211
  onRenderTextLayerError?: OnRenderTextLayerError;
212
  onRenderTextLayerSuccess?: OnRenderTextLayerSuccess;
213
  page: PDFPageProxy | false | undefined;
214
  pageIndex: number;
215
  pageNumber: number;
216
  renderForms: boolean;
217
  renderTextLayer: boolean;
218
  rotate: number;
219
  scale: number;
220
}
221

222
interface OutlineContextType {
223
  onItemClick?: (args: OnItemClickArgs) => void;
224
}
225
```
226

227
[Context Hooks](./context-hooks.md)
228

229
## Types
230

231
### Core Types
232

233
```typescript { .api }
234
interface PDFDocumentProxy {
235
  numPages: number;
236
  getPage(pageNumber: number): Promise<PDFPageProxy>;
237
  getOutline(): Promise<PDFOutline | null>;
238
}
239

240
interface PDFPageProxy {
241
  pageNumber: number;
242
  rotate: number;
243
  getViewport(params: { scale: number; rotation?: number }): PageViewport;
244
  render(params: RenderParameters): RenderTask;
245
  getTextContent(): Promise<TextContent>;
246
  getAnnotations(): Promise<Annotations>;
247
}
248

249
interface PageViewport {
250
  width: number;
251
  height: number;
252
  transform: number[];
253
}
254

255
type ClassName = string | null | undefined | (string | null | undefined)[];
256

257
type NodeOrRenderer = React.ReactNode | (() => React.ReactNode);
258

259
type RegisterPage = (pageIndex: number, ref: HTMLDivElement) => void;
260

261
type UnregisterPage = (pageIndex: number) => void;
262

263
type Annotations = any[]; // PDF.js annotation types
264

265
type CustomTextRenderer = (
266
  props: { pageIndex: number; pageNumber: number; itemIndex: number } & TextItem,
267
) => string;
268

269
interface Options extends Omit<DocumentInitParameters, 'url' | 'data' | 'range'> {
270
  cMapUrl?: string;
271
  httpHeaders?: Record<string, string>;
272
  wasmUrl?: string;
273
  withCredentials?: boolean;
274
}
275

276
// LinkService class for handling PDF links and navigation
277
class LinkService {
278
  externalLinkEnabled: boolean;
279
  externalLinkRel?: ExternalLinkRel;
280
  externalLinkTarget?: ExternalLinkTarget;
281
  isInPresentationMode: boolean;
282
  pdfDocument?: PDFDocumentProxy | null;
283
  pdfViewer?: any | null;
284

285
  constructor();
286
  setDocument(pdfDocument: PDFDocumentProxy | null): void;
287
  setViewer(pdfViewer: any): void;
288
  getDestinationHash(dest: string | any[]): string;
289
  getAnchorUrl(hash: string): string;
290
  setHash(hash: string): void;
291
  executeNamedAction(action: string): void;
292
  onFileAttachmentAnnotation(): void;
293
  cachePageRef(pageNum: number, pageRef: any): void;
294
  isPageVisible(pageNumber: number): boolean;
295
  isPageCached(pageNumber: number): boolean;
296
}
297
```
298

299
### Event Handler Types
300

301
```typescript { .api }
302
type OnDocumentLoadSuccess = (document: PDFDocumentProxy) => void;
303
type OnDocumentLoadError = (error: Error) => void;
304
type OnDocumentLoadProgress = (args: { loaded: number; total: number }) => void;
305
type OnPageLoadSuccess = (page: PageCallback) => void;
306
type OnPageLoadError = (error: Error) => void;
307
type OnPasswordCallback = (password: string | null) => void;
308
type OnGetAnnotationsError = (error: Error) => void;
309
type OnGetAnnotationsSuccess = (annotations: Annotations) => void;
310
type OnGetStructTreeError = (error: Error) => void;
311
type OnGetStructTreeSuccess = (tree: StructTreeNode) => void;
312
type OnGetTextError = (error: Error) => void;
313
type OnGetTextSuccess = (textContent: TextContent) => void;
314
type OnRenderAnnotationLayerError = (error: unknown) => void;
315
type OnRenderAnnotationLayerSuccess = () => void;
316
type OnRenderError = (error: Error) => void;
317
type OnRenderSuccess = (page: PageCallback) => void;
318
type OnRenderTextLayerError = (error: Error) => void;
319
type OnRenderTextLayerSuccess = () => void;
320

321
// PasswordResponses constant object
322
const PasswordResponses = {
323
  NEED_PASSWORD: 1,
324
  INCORRECT_PASSWORD: 2,
325
} as const;
326

327
type PasswordResponse = (typeof PasswordResponses)[keyof typeof PasswordResponses];
328
```
329

330
### PDF.js Types
331

332
Types re-exported from PDF.js for text content, structure tree, and annotations.
333

334
```typescript { .api }
335
interface TextContent {
336
  items: (TextItem | TextMarkedContent)[];
337
  styles: Record<string, TextStyle>;
338
}
339

340
interface TextItem {
341
  str: string;
342
  dir: string;
343
  width: number;
344
  height: number;
345
  transform: number[];
346
  fontName: string;
347
}
348

349
interface TextMarkedContent {
350
  type: string;
351
}
352

353
interface StructTreeNode {
354
  role?: string;
355
  children?: StructTreeNode[];
356
  alt?: string;
357
  lang?: string;
358
}
359

360
interface TextStyle {
361
  ascent: number;
362
  descent: number;
363
  vertical: boolean;
364
  fontFamily: string;
365
  fontSize: number;
366
}
367
```
368

369
### Render Props Types
370

371
```typescript { .api }
372
interface DocumentRenderProps {
373
  pdf: PDFDocumentProxy;
374
  linkService: LinkService;
375
  registerPage: (pageIndex: number, ref: HTMLDivElement) => void;
376
  unregisterPage: (pageIndex: number) => void;
377
}
378

379
interface PageRenderProps {
380
  page: PDFPageProxy;
381
  pageIndex: number;
382
  pageNumber: number;
383
  scale: number;
384
  rotate: number;
385
}
386
```