0
# @react-pdf/types
1

2
@react-pdf/types provides comprehensive TypeScript definitions for the react-pdf library ecosystem, enabling type-safe development when creating PDF documents using React components. The package includes type definitions for all core react-pdf functionality including PDF documents, pages, text rendering, styling, images, SVG elements, fonts, bookmarks, and rendering contexts.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import type { 
15
  DocumentNode, 
16
  PageNode, 
17
  ViewNode, 
18
  TextNode,
19
  Style,
20
  PDFVersion,
21
  Primitive,
22
  Context
23
} from "@react-pdf/types";
24
```
25

26
For specific categories:
27

28
```typescript
29
// Document and node types
30
import type { DocumentNode, PageNode, ViewNode, TextNode } from "@react-pdf/types";
31

32
// Styling system
33
import type { Style } from "@react-pdf/types";
34

35
// Font system  
36
import type { FontStyle, FontWeight, FontDescriptor } from "@react-pdf/types";
37

38
// Image handling
39
import type { SourceObject } from "@react-pdf/types";
40

41
// SVG support
42
import type { SVGPresentationAttributes } from "@react-pdf/types";
43

44
// Primitive elements
45
import { Primitive } from "@react-pdf/types";
46
```
47

48
## Basic Usage
49

50
```typescript
51
import type { 
52
  DocumentNode, 
53
  PageNode, 
54
  ViewNode, 
55
  TextNode, 
56
  Style,
57
  PDFVersion 
58
} from "@react-pdf/types";
59
import { Primitive } from "@react-pdf/types";
60

61
// Define styled components with proper typing
62
const pageStyle: Style = {
63
  flexDirection: 'column',
64
  backgroundColor: '#ffffff',
65
  padding: 20
66
};
67

68
const textStyle: Style = {
69
  fontSize: 12,
70
  fontFamily: 'Helvetica',
71
  color: '#333333'
72
};
73

74
// Type PDF document structure
75
const document: DocumentNode = {
76
  type: Primitive.Document,
77
  props: {
78
    title: 'My PDF Document',
79
    author: 'John Doe',
80
    subject: 'Sample PDF'
81
  },
82
  children: [{
83
    type: Primitive.Page,
84
    style: pageStyle,
85
    props: {
86
      size: 'A4',
87
      orientation: 'portrait'
88
    },
89
    children: [{
90
      type: Primitive.View,
91
      style: { padding: 10 },
92
      children: [{
93
        type: Primitive.Text,
94
        style: textStyle,
95
        children: [{
96
          type: Primitive.TextInstance,
97
          value: 'Hello, World!'
98
        }]
99
      }]
100
    }]
101
  }]
102
};
103
```
104

105
## Capabilities
106

107
### Document Structure Types
108

109
Core node types representing the PDF document structure.
110

111
```typescript { .api }
112
// Root document node
113
interface DocumentNode {
114
  type: Primitive.Document;
115
  props?: DocumentProps;
116
  children: PageNode[];
117
}
118

119
// Page container node
120
interface PageNode {
121
  type: Primitive.Page;
122
  style?: Style;
123
  props?: PageProps;
124
  children?: (ViewNode | TextNode)[];
125
}
126

127
// View container node
128
interface ViewNode {
129
  type: Primitive.View;
130
  style?: Style;
131
  props?: ViewProps;
132
  children?: (ViewNode | TextNode)[];
133
}
134

135
// Text content node
136
interface TextNode {
137
  type: Primitive.Text;
138
  lines?: any[];
139
  style?: Style;
140
  props?: TextProps;
141
  children?: TextInstanceNode[];
142
}
143

144
// Text instance node
145
interface TextInstanceNode {
146
  type: Primitive.TextInstance;
147
  value: string;
148
}
149

150
// Union type of all nodes
151
type Node = DocumentNode | PageNode | ViewNode;
152
```
153

154
### Document Properties
155

156
Properties for configuring PDF document metadata and behavior.
157

158
```typescript { .api }
159
interface DocumentProps {
160
  title?: string;
161
  author?: string;
162
  subject?: string;
163
  keywords?: string;
164
  creator?: string;
165
  producer?: string;
166
  creationDate?: Date;
167
  modificationDate?: Date;
168
  pageLayout?: PageLayout;
169
  pageMode?: PageMode;
170
}
171

172
type PageLayout =
173
  | 'singlePage'
174
  | 'oneColumn'
175
  | 'twoColumnLeft'
176
  | 'twoColumnRight'
177
  | 'twoPageLeft'
178
  | 'twoPageRight';
179

180
type PageMode =
181
  | 'useNone'
182
  | 'useOutlines'
183
  | 'useThumbs'
184
  | 'fullScreen'
185
  | 'useOC'
186
  | 'useAttachments';
187
```
188

189
### Base Component Properties
190

191
Common properties shared across different component types.
192

193
```typescript { .api }
194
interface BaseProps {
195
  id?: string;
196
  fixed?: boolean;
197
  break?: boolean;
198
  debug?: boolean;
199
  bookmark?: Bookmark;
200
  minPresenceAhead?: number;
201
}
202

203
interface TextProps extends BaseProps {
204
  wrap?: boolean;
205
  widows?: number;
206
  orphans?: number;
207
  render?: DynamicRenderCallback;
208
  hyphenationCallback?: HyphenationCallback;
209
}
210

211
interface ViewProps extends BaseProps {
212
  wrap?: boolean;
213
  render?: (props: { pageNumber: number }) => any;
214
}
215

216
interface PageProps extends BaseProps {
217
  wrap?: boolean;
218
  size?: PageSize;
219
  orientation?: Orientation;
220
  dpi?: number;
221
}
222

223
type DynamicRenderCallback = (props: {
224
  pageNumber: number;
225
  totalPages: number;
226
}) => any;
227
```
228

229
### Page Configuration
230

231
Types for defining page sizes and orientations.
232

233
```typescript { .api }
234
type Orientation = 'portrait' | 'landscape';
235

236
type PageSize =
237
  | StandardPageSize
238
  | [StaticSize]
239
  | [StaticSize, StaticSize]
240
  | { width: StaticSize; height?: StaticSize };
241

242
type StandardPageSize =
243
  | '4A0' | '2A0' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'A7' | 'A8' | 'A9' | 'A10'
244
  | 'B0' | 'B1' | 'B2' | 'B3' | 'B4' | 'B5' | 'B6' | 'B7' | 'B8' | 'B9' | 'B10'
245
  | 'C0' | 'C1' | 'C2' | 'C3' | 'C4' | 'C5' | 'C6' | 'C7' | 'C8' | 'C9' | 'C10'
246
  | 'RA0' | 'RA1' | 'RA2' | 'RA3' | 'RA4'
247
  | 'SRA0' | 'SRA1' | 'SRA2' | 'SRA3' | 'SRA4'
248
  | 'EXECUTIVE' | 'FOLIO' | 'LEGAL' | 'LETTER' | 'TABLOID' | 'ID1';
249

250
type StaticSize = number | string;
251
```
252

253
### PDF Version Support
254

255
PDF version specification for document compatibility.
256

257
```typescript { .api }
258
type PDFVersion = '1.3' | '1.4' | '1.5' | '1.6' | '1.7' | '1.7ext3';
259
```
260

261
### Styling System
262

263
Comprehensive CSS-like styling system for PDF elements.
264

265
```typescript { .api }
266
// Main style interface (re-exported from @react-pdf/stylesheet)
267
interface Style {
268
  // Layout properties
269
  display?: 'flex' | 'none';
270
  position?: 'absolute' | 'relative' | 'static';
271
  top?: number | string;
272
  right?: number | string;
273
  bottom?: number | string;
274
  left?: number | string;
275
  zIndex?: number | string;
276
  overflow?: 'hidden';
277
  aspectRatio?: number | string;
278

279
  // Dimensions
280
  width?: number | string;
281
  height?: number | string;
282
  minWidth?: number | string;
283
  minHeight?: number | string;
284
  maxWidth?: number | string;
285
  maxHeight?: number | string;
286

287
  // Flexbox
288
  flex?: number | string;
289
  flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
290
  flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
291
  flexGrow?: number | string;
292
  flexShrink?: number | string;
293
  flexBasis?: number | string;
294
  alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
295
  alignSelf?: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
296
  alignContent?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'space-between' | 'space-around' | 'space-evenly';
297
  justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-around' | 'space-between' | 'space-evenly';
298

299
  // Spacing
300
  margin?: number | string;
301
  marginTop?: number | string;
302
  marginRight?: number | string;
303
  marginBottom?: number | string;
304
  marginLeft?: number | string;
305
  marginHorizontal?: number | string;
306
  marginVertical?: number | string;
307
  padding?: number | string;
308
  paddingTop?: number | string;
309
  paddingRight?: number | string;
310
  paddingBottom?: number | string;
311
  paddingLeft?: number | string;
312
  paddingHorizontal?: number | string;
313
  paddingVertical?: number | string;
314

315
  // Gap
316
  gap?: number | string;
317
  rowGap?: number | string;
318
  columnGap?: number | string;
319

320
  // Colors
321
  color?: string;
322
  backgroundColor?: string;
323
  opacity?: number | string;
324

325
  // Typography
326
  fontSize?: number | string;
327
  fontFamily?: string | string[];
328
  fontStyle?: 'normal' | 'italic' | 'oblique';
329
  fontWeight?: FontWeight;
330
  lineHeight?: number | string;
331
  letterSpacing?: number | string;
332
  textAlign?: 'left' | 'right' | 'center' | 'justify';
333
  textDecoration?: 'line-through' | 'underline' | 'none' | 'line-through underline' | 'underline line-through';
334
  textDecorationColor?: string;
335
  textDecorationStyle?: 'dashed' | 'dotted' | 'solid' | string;
336
  textTransform?: 'capitalize' | 'lowercase' | 'uppercase' | 'upperfirst' | 'none';
337
  textIndent?: any;
338
  textOverflow?: 'ellipsis';
339
  verticalAlign?: 'sub' | 'super';
340
  direction?: 'ltr' | 'rtl';
341
  maxLines?: number;
342

343
  // Borders
344
  border?: number | string;
345
  borderTop?: number | string;
346
  borderRight?: number | string;
347
  borderBottom?: number | string;
348
  borderLeft?: number | string;
349
  borderColor?: string;
350
  borderRadius?: number | string;
351
  borderStyle?: 'dashed' | 'dotted' | 'solid';
352
  borderWidth?: number | string;
353
  borderTopColor?: string;
354
  borderTopStyle?: 'dashed' | 'dotted' | 'solid';
355
  borderTopWidth?: number | string;
356
  borderRightColor?: string;
357
  borderRightStyle?: 'dashed' | 'dotted' | 'solid';
358
  borderRightWidth?: number | string;
359
  borderBottomColor?: string;
360
  borderBottomStyle?: 'dashed' | 'dotted' | 'solid';
361
  borderBottomWidth?: number | string;
362
  borderLeftColor?: string;
363
  borderLeftStyle?: 'dashed' | 'dotted' | 'solid';
364
  borderLeftWidth?: number | string;
365
  borderTopLeftRadius?: number | string;
366
  borderTopRightRadius?: number | string;
367
  borderBottomRightRadius?: number | string;
368
  borderBottomLeftRadius?: number | string;
369

370
  // Transforms
371
  transform?: string | Transform[];
372
  transformOrigin?: number | string;
373
  transformOriginX?: number | string;
374
  transformOriginY?: number | string;
375

376
  // Object positioning
377
  objectPosition?: number | string;
378
  objectPositionX?: number | string;
379
  objectPositionY?: number | string;
380
  objectFit?: string;
381

382
  // SVG-specific properties
383
  fill?: string;
384
  stroke?: string;
385
  strokeDasharray?: string;
386
  strokeWidth?: string | number;
387
  fillOpacity?: string | number;
388
  fillRule?: 'nonzero' | 'evenodd';
389
  strokeOpacity?: string | number;
390
  textAnchor?: 'start' | 'middle' | 'end';
391
  strokeLinecap?: 'butt' | 'round' | 'square';
392
  strokeLinejoin?: 'butt' | 'round' | 'square' | 'miter' | 'bevel';
393
  visibility?: 'visible' | 'hidden' | 'collapse';
394
  clipPath?: string;
395
  dominantBaseline?: 'auto' | 'middle' | 'central' | 'hanging' | 'mathematical' | 'text-after-edge' | 'text-before-edge';
396

397
  // Media queries
398
  [key: `@media${string}`]: Style;
399
}
400
```
401

402
### Transform Types
403

404
Transform operations for element positioning and effects.
405

406
```typescript { .api }
407
type Transform =
408
  | ScaleTransform
409
  | TranslateTransform
410
  | RotateTransform
411
  | SkewTransform
412
  | MatrixTransform;
413

414
interface ScaleTransform {
415
  operation: 'scale';
416
  value: [number, number];
417
}
418

419
interface TranslateTransform {
420
  operation: 'translate';
421
  value: [number, number];
422
}
423

424
interface RotateTransform {
425
  operation: 'rotate';
426
  value: [number];
427
}
428

429
interface SkewTransform {
430
  operation: 'skew';
431
  value: [number, number];
432
}
433

434
interface MatrixTransform {
435
  operation: 'matrix';
436
  value: [number, number, number, number, number, number];
437
}
438
```
439

440
### Font System
441

442
Font-related types for typography configuration.
443

444
```typescript { .api }
445
// Font weight values
446
type FontWeight =
447
  | number
448
  | 'thin' | 'ultralight' | 'light' | 'normal' | 'medium' 
449
  | 'semibold' | 'bold' | 'ultrabold' | 'heavy';
450

451
// Font style values
452
type FontStyle = 'normal' | 'italic' | 'oblique';
453

454
// Font descriptor for font selection
455
interface FontDescriptor {
456
  fontFamily: string;
457
  fontStyle?: FontStyle;
458
  fontWeight?: FontWeight;
459
}
460

461
// Emoji source configuration
462
type EmojiSource = EmojiSourceUrl | EmojiSourceBuilder;
463

464
interface EmojiSourceUrl {
465
  url: string;
466
  format?: string;
467
  withVariationSelectors?: boolean;
468
}
469

470
interface EmojiSourceBuilder {
471
  builder: (code: string) => string;
472
  withVariationSelectors?: boolean;
473
}
474

475
// Hyphenation callback
476
type HyphenationCallback = (word: string) => string[];
477

478
// Font store for managing fonts
479
type FontStore = FontStoreType;
480
```
481

482
### Image Handling
483

484
Types for handling various image source formats and configurations.
485

486
```typescript { .api }
487
// Main image source type
488
type SourceObject =
489
  | Source
490
  | SourceFactory
491
  | SourceAsync
492
  | SourceAsyncFactory;
493

494
// Base source types
495
type Source =
496
  | SourceURL
497
  | SourceBuffer
498
  | SourceBlob
499
  | SourceDataBuffer
500
  | SourceURLObject
501
  | undefined;
502

503
type SourceURL = string;
504
type SourceBuffer = Buffer;
505
type SourceBlob = Blob;
506

507
interface SourceDataBuffer {
508
  data: Buffer;
509
  format: 'png' | 'jpg';
510
}
511

512
interface SourceURLObject {
513
  uri: string;
514
  method?: HTTPMethod;
515
  body?: any;
516
  headers?: any;
517
  credentials?: 'omit' | 'same-origin' | 'include';
518
}
519

520
// Factory and async types
521
type SourceFactory = () => Source;
522
type SourceAsync = Promise<Source>;
523
type SourceAsyncFactory = () => Promise<Source>;
524

525
type HTTPMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
526
```
527

528
### SVG Support
529

530
SVG presentation attributes for vector graphics styling.
531

532
```typescript { .api }
533
interface SVGPresentationAttributes {
534
  fill?: string;
535
  color?: string;
536
  stroke?: string;
537
  transform?: string;
538
  strokeDasharray?: string;
539
  opacity?: string | number;
540
  strokeWidth?: string | number;
541
  fillOpacity?: string | number;
542
  fillRule?: 'nonzero' | 'evenodd';
543
  strokeOpacity?: string | number;
544
  textAnchor?: 'start' | 'middle' | 'end';
545
  strokeLinecap?: 'butt' | 'round' | 'square';
546
  strokeLinejoin?: 'butt' | 'round' | 'square' | 'miter' | 'bevel';
547
  visibility?: 'visible' | 'hidden' | 'collapse';
548
  clipPath?: string;
549
  dominantBaseline?:
550
    | 'auto' | 'middle' | 'central' | 'hanging' | 'mathematical'
551
    | 'text-after-edge' | 'text-before-edge';
552
}
553
```
554

555
### Primitive Elements
556

557
Enumeration of all available PDF element types.
558

559
```typescript { .api }
560
enum Primitive {
561
  // Document structure
562
  Document = 'DOCUMENT',
563
  Page = 'PAGE',
564
  
565
  // Containers
566
  View = 'VIEW',
567
  G = 'G', // SVG group
568
  
569
  // Text elements
570
  Text = 'TEXT',
571
  Tspan = 'TSPAN',
572
  TextInstance = 'TEXT_INSTANCE',
573
  
574
  // Media elements
575
  Image = 'IMAGE',
576
  Canvas = 'CANVAS',
577
  
578
  // Form elements
579
  FieldSet = 'FIELD_SET',
580
  TextInput = 'TEXT_INPUT',
581
  Select = 'SELECT',
582
  Checkbox = 'CHECKBOX',
583
  List = 'LIST',
584
  
585
  // SVG shapes
586
  Svg = 'SVG',
587
  Path = 'PATH',
588
  Rect = 'RECT',
589
  Line = 'LINE',
590
  Circle = 'CIRCLE',
591
  Ellipse = 'ELLIPSE',
592
  Polygon = 'POLYGON',
593
  Polyline = 'POLYLINE',
594
  
595
  // SVG utilities
596
  ClipPath = 'CLIP_PATH',
597
  Defs = 'DEFS',
598
  Stop = 'STOP',
599
  LinearGradient = 'LINEAR_GRADIENT',
600
  RadialGradient = 'RADIAL_GRADIENT',
601
  
602
  // Interactive elements
603
  Link = 'LINK',
604
  Note = 'NOTE'
605
}
606
```
607

608
### Bookmark System
609

610
Types for creating PDF bookmarks and navigation.
611

612
```typescript { .api }
613
type Bookmark = string | ExpandedBookmark;
614

615
interface ExpandedBookmark {
616
  title: string;
617
  top?: number;
618
  left?: number;
619
  zoom?: number;
620
  fit?: true | false;
621
  expanded?: true | false;
622
}
623
```
624

625
### Rendering Context
626

627
Low-level rendering context interface for custom drawing operations.
628

629
```typescript { .api }
630
interface Context {
631
  info: DocumentInfo;
632
  
633
  // Document control
634
  end: () => void;
635
  
636
  // State management
637
  save: () => this;
638
  restore: () => this;
639
  
640
  // Line styling
641
  lineCap(c: string): this;
642
  miterLimit(m: any): this;
643
  lineJoin(j: string): this;
644
  lineWidth(w: number): this;
645
  dash(length: number, option: any): this;
646
  undash(): this;
647
  
648
  // Colors and opacity
649
  fill(color?: ColorValue): this;
650
  stroke(color?: ColorValue): this;
651
  fillColor(color: ColorValue, opacity?: number): this;
652
  strokeColor(color: ColorValue, opacity?: number): this;
653
  opacity(opacity: number): this;
654
  fillOpacity(opacity: number): this;
655
  strokeOpacity(opacity: number): this;
656
  
657
  // Path operations
658
  moveTo(x: number, y: number): this;
659
  lineTo(x: number, y: number): this;
660
  quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): this;
661
  bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): this;
662
  
663
  // Shape drawing
664
  rect(x: number, y: number, w: number, h: number): this;
665
  roundedRect(x: number, y: number, w: number, h: number, r?: number): this;
666
  circle(x: number, y: number, radius: number): this;
667
  ellipse(x: number, y: number, r1: number, r2?: number): this;
668
  polygon(...points: number[][]): this;
669
  
670
  // Page management
671
  addPage(options?: PageOption): this;
672
  
673
  // Image handling
674
  image(src: any, x?: number, y?: number, options?: ImageOption): Context;
675
}
676

677
interface DocumentInfo {
678
  Producer?: string;
679
  Creator?: string;
680
  CreationDate?: Date;
681
  Title?: string;
682
  Author?: string;
683
  Keywords?: string;
684
  ModDate?: Date;
685
}
686

687
interface PageOption {
688
  margin?: number;
689
  size?: number[] | string;
690
}
691

692
interface ImageOption {
693
  width?: number;
694
  height?: number;
695
}
696

697
type ColorValue = string;
698
```
699

700
## Types
701

702
All types in this package are TypeScript definition-only and provide no runtime functionality. They are designed to be used with the main `react-pdf` package for type safety and IntelliSense support in TypeScript projects.
703

704
The package re-exports types from three core dependencies:
705
- `@react-pdf/font`: Font management and typography types
706
- `@react-pdf/stylesheet`: Comprehensive CSS-like styling system
707
- `@react-pdf/primitives`: Element type constants and enumerations