0
# PDFKit
1

2
PDFKit is a comprehensive PDF generation library for Node.js and browsers that enables developers to create complex, multi-page, printable documents programmatically. It offers both low-level PDF operations and high-level abstractions for vector graphics, advanced text handling, font embedding, image integration, interactive forms, and accessibility features.
3

4
## Package Information
5

6
- **Package Name**: pdfkit
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install pdfkit`
10

11
## Core Imports
12

13
```javascript
14
import PDFDocument from "pdfkit";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const PDFDocument = require("pdfkit");
21
```
22

23
For browsers:
24

25
```html
26
<script src="path/to/pdfkit.standalone.js"></script>
27
<!-- PDFDocument is available globally -->
28
```
29

30
## Basic Usage
31

32
```javascript
33
import PDFDocument from "pdfkit";
34
import fs from "fs";
35

36
// Create a new PDF document
37
const doc = new PDFDocument({
38
  size: 'A4',
39
  margins: { top: 50, left: 50, right: 50, bottom: 50 }
40
});
41

42
// Pipe the PDF to a file
43
doc.pipe(fs.createWriteStream('output.pdf'));
44

45
// Add content
46
doc.fontSize(20)
47
   .fillColor('blue')
48
   .text('Hello PDFKit!', 100, 100);
49

50
doc.rect(100, 150, 200, 100)
51
   .fillColor('red')
52
   .fill();
53

54
// Finalize the PDF
55
doc.end();
56
```
57

58
## Architecture
59

60
PDFKit is built around several key components:
61

62
- **PDFDocument Class**: Main class extending Node.js Readable stream for PDF generation
63
- **Mixin Architecture**: Functionality organized into specialized mixins (Color, Vector, Text, Images, etc.)
64
- **Page Management**: Automatic and manual page handling with buffering support
65
- **Stream-Based Output**: Compatible with Node.js streams for flexible output handling
66
- **Cross-Platform**: Works in Node.js and modern browsers with different build targets
67

68
## Capabilities
69

70
### Document Management
71

72
Core document creation, page management, and output control functionality.
73

74
```javascript { .api }
75
class PDFDocument extends stream.Readable {
76
  constructor(options?: PDFDocumentOptions);
77
  addPage(options?: PageOptions): PDFDocument;
78
  end(): void;
79
}
80

81
interface PDFDocumentOptions {
82
  pdfVersion?: '1.3' | '1.4' | '1.5' | '1.6' | '1.7' | '1.7ext3';
83
  compress?: boolean;
84
  autoFirstPage?: boolean;
85
  size?: string | [number, number];
86
  layout?: 'portrait' | 'landscape';
87
  margins?: MarginDefinition;
88
  bufferPages?: boolean;
89
  font?: string | Buffer | ArrayBuffer;
90
  fontSize?: number;
91
  info?: DocumentInfo;
92
  displayTitle?: boolean;
93
  lang?: string;
94
  ignoreOrientation?: boolean;
95
  subset?: PDFSubset;
96
  tagged?: boolean;
97
}
98
```
99

100
[Document Management](./document-management.md)
101

102
### Text Rendering
103

104
Advanced text rendering with flexible positioning, styling, fonts, and layout options including line wrapping and multi-column support.
105

106
```javascript { .api }
107
text(text: string, x?: number, y?: number, options?: TextOptions): PDFDocument;
108
widthOfString(string: string, options?: TextOptions): number;
109
font(src: string | Buffer, family?: string, size?: number): PDFDocument;
110
fontSize(size: SizeValue): PDFDocument;
111
```
112

113
[Text Rendering](./text-rendering.md)
114

115
### Vector Graphics
116

117
Comprehensive vector graphics with path construction, shapes, transformations, and painting operations using HTML5 canvas-like API.
118

119
```javascript { .api }
120
rect(x: number, y: number, w: number, h: number): PDFDocument;
121
circle(x: number, y: number, radius: number): PDFDocument;
122
moveTo(x: number, y: number): PDFDocument;
123
lineTo(x: number, y: number): PDFDocument;
124
fill(color?: ColorValue, rule?: FillRule): PDFDocument;
125
stroke(color?: ColorValue): PDFDocument;
126
```
127

128
[Vector Graphics](./vector-graphics.md)
129

130
### Color Management
131

132
Color handling with support for RGB, CMYK, hex colors, gradients, patterns, and spot colors.
133

134
```javascript { .api }
135
fillColor(color: ColorValue, opacity?: number): PDFDocument;
136
strokeColor(color: ColorValue, opacity?: number): PDFDocument;
137
linearGradient(x1: number, y1: number, x2: number, y2: number): Gradient;
138
radialGradient(x1: number, y1: number, r1: number, x2: number, y2: number, r2: number): Gradient;
139
```
140

141
[Color Management](./color-management.md)
142

143
### Image Handling
144

145
Image embedding and rendering with support for JPEG and PNG formats, including transparent PNGs and EXIF orientation.
146

147
```javascript { .api }
148
image(src: ImageSource, x?: number, y?: number, options?: ImageOptions): PDFDocument;
149
openImage(src: ImageSource): PDFImage;
150

151
type ImageSource = string | Buffer | ArrayBuffer;
152
```
153

154
[Image Handling](./image-handling.md)
155

156
### Interactive Elements
157

158
Annotations, hyperlinks, form fields, and interactive PDF features for creating engaging documents.
159

160
```javascript { .api }
161
link(x: number, y: number, w: number, h: number, url: string, options?: AnnotationOptions): PDFDocument;
162
formText(name: string, x: number, y: number, w: number, h: number, options?: FormFieldOptions): PDFDocument;
163
note(x: number, y: number, w: number, h: number, contents: string, options?: AnnotationOptions): PDFDocument;
164
```
165

166
[Interactive Elements](./interactive-elements.md)
167

168
### Font Management
169

170
Advanced font handling with font registration, size utilities, and typography controls.
171

172
```javascript { .api }
173
font(src: string | Buffer | ArrayBuffer, family?: string, size?: number): PDFDocument;
174
fontSize(size: SizeValue): PDFDocument;
175
registerFont(name: string, src: string | Buffer | ArrayBuffer, family?: string): PDFDocument;
176
currentLineHeight(includeGap?: boolean): number;
177
```
178

179
[Font Management](./font-management.md)
180

181
### Document Outline
182

183
PDF bookmarks and navigation structure for creating organized document outlines.
184

185
```javascript { .api }
186
outline.addItem(title: string, options?: OutlineOptions): OutlineItem;
187

188
interface OutlineOptions {
189
  expanded?: boolean;
190
  destination?: string;
191
}
192
```
193

194
[Document Outline](./outline.md)
195

196
### File Attachments
197

198
Embed files within PDF documents for comprehensive document packages.
199

200
```javascript { .api }
201
file(src: string | Buffer, options?: FileOptions): PDFReference;
202

203
interface FileOptions {
204
  name?: string;
205
  type?: string;
206
  description?: string;
207
  hidden?: boolean;
208
  creationDate?: Date;
209
  modifiedDate?: Date;
210
}
211
```
212

213
[File Attachments](./attachments.md)
214

215
### Tables
216

217
Structured table creation with comprehensive layout and styling options.
218

219
```javascript { .api }
220
table(options?: TableOptions): PDFTable;
221

222
interface PDFTable {
223
  row(data: any[], lastRow?: boolean): PDFTable | PDFDocument;
224
  end(): PDFDocument;
225
}
226
```
227

228
[Tables](./tables.md)
229

230
### Accessibility Features
231

232
Tagged PDF support, structure elements, and accessibility features for creating inclusive documents.
233

234
```javascript { .api }
235
struct(type: StructureType, options?: StructureOptions, children?: StructureElement[]): StructureElement;
236
markContent(tag: string, options?: MarkingOptions): PDFDocument;
237
```
238

239
[Accessibility Features](./accessibility-features.md)
240

241
## Types
242

243
```javascript { .api }
244
type ColorValue = string | [number, number, number] | [number, number, number, number] | Gradient | Pattern;
245
type SizeValue = number | string;
246
type MarginDefinition = number | [number, number] | [number, number, number, number] | 
247
  { vertical: number; horizontal: number } | 
248
  { top: number; right: number; bottom: number; left: number };
249

250
interface DocumentInfo {
251
  Title?: string;
252
  Author?: string;
253
  Subject?: string;
254
  Keywords?: string;
255
  Creator?: string;
256
  Producer?: string;
257
  CreationDate?: Date;
258
  ModDate?: Date;
259
}
260

261
type PDFSubset = 'PDF/A-1' | 'PDF/A-1a' | 'PDF/A-1b' | 'PDF/A-2' | 'PDF/A-2a' | 'PDF/A-2b' | 'PDF/A-3' | 'PDF/A-3a' | 'PDF/A-3b' | 'PDF/UA';
262

263
// Standard page sizes supported
264
type PageSize = 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'A7' | 'A8' | 'A9' | 'A10' |
265
  'B0' | 'B1' | 'B2' | 'B3' | 'B4' | 'B5' | 'B6' | 'B7' | 'B8' | 'B9' | 'B10' |
266
  'C0' | 'C1' | 'C2' | 'C3' | 'C4' | 'C5' | 'C6' | 'C7' | 'C8' | 'C9' | 'C10' |
267
  'RA0' | 'RA1' | 'RA2' | 'RA3' | 'RA4' | 'SRA0' | 'SRA1' | 'SRA2' | 'SRA3' | 'SRA4' |
268
  'EXECUTIVE' | 'FOLIO' | 'LEGAL' | 'LETTER' | 'TABLOID';
269
```