0
# Font Management
1

2
Advanced font handling with font registration, size utilities, and typography controls for professional document typography.
3

4
## Capabilities
5

6
### Font Selection
7

8
Set the current font for text rendering operations.
9

10
```javascript { .api }
11
/**
12
 * Set the current font
13
 * @param src - Font source (built-in name, file path, or Buffer)
14
 * @param family - Font family name (optional)
15
 * @param size - Font size in points (optional)
16
 * @returns Document instance for chaining
17
 */
18
font(src: string | Buffer | ArrayBuffer, family?: string, size?: number): PDFDocument;
19
```
20

21
**Built-in Fonts:**
22
- `'Helvetica'` (default)
23
- `'Helvetica-Bold'`
24
- `'Helvetica-Oblique'`
25
- `'Helvetica-BoldOblique'`
26
- `'Times-Roman'`
27
- `'Times-Bold'`
28
- `'Times-Italic'`
29
- `'Times-BoldItalic'`
30
- `'Courier'`
31
- `'Courier-Bold'`
32
- `'Courier-Oblique'`
33
- `'Courier-BoldOblique'`
34
- `'Symbol'`
35
- `'ZapfDingbats'`
36

37
**Usage Examples:**
38

39
```javascript
40
// Use built-in font
41
doc.font('Helvetica-Bold');
42

43
// Load custom font from file
44
doc.font('./assets/custom-font.ttf');
45

46
// Load font from Buffer
47
const fontBuffer = fs.readFileSync('./assets/font.otf');
48
doc.font(fontBuffer);
49

50
// Set font with family name and size
51
doc.font('./assets/custom.ttf', 'Custom Font', 14);
52
```
53

54
### Font Size
55

56
Set the current font size for text rendering.
57

58
```javascript { .api }
59
/**
60
 * Set the current font size
61
 * @param size - Font size (supports various units)
62
 * @returns Document instance for chaining
63
 */
64
fontSize(size: SizeValue): PDFDocument;
65
```
66

67
**Supported Size Units:**
68
- Numbers (points): `12`, `14.5`
69
- Unit strings: `'12pt'`, `'1em'`, `'16px'`, `'1in'`, `'10mm'`, `'1cm'`
70
- Relative units: `'120%'`, `'1.2em'`
71

72
**Usage Examples:**
73

74
```javascript
75
// Set font size in points
76
doc.fontSize(12);
77

78
// Set font size with units
79
doc.fontSize('14pt');
80
doc.fontSize('1.2em');
81
doc.fontSize('16px');
82

83
// Chain with text
84
doc.fontSize(18).text('Large heading', 100, 100);
85
```
86

87
### Font Registration
88

89
Register custom fonts for use by name throughout the document.
90

91
```javascript { .api }
92
/**
93
 * Register a font for use by name
94
 * @param name - Name to register the font under
95
 * @param src - Font source (file path or Buffer)
96
 * @param family - Font family name (optional)
97
 * @returns Document instance for chaining
98
 */
99
registerFont(name: string, src: string | Buffer | ArrayBuffer, family?: string): PDFDocument;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
// Register custom fonts
106
doc.registerFont('MyFont', './assets/custom.ttf')
107
   .registerFont('MyBold', './assets/custom-bold.ttf')
108
   .registerFont('MyItalic', './assets/custom-italic.ttf');
109

110
// Use registered fonts by name
111
doc.font('MyFont').text('Regular text', 100, 100);
112
doc.font('MyBold').text('Bold text', 100, 120);
113
doc.font('MyItalic').text('Italic text', 100, 140);
114
```
115

116
### Typography Utilities
117

118
Utility methods for font and layout calculations.
119

120
```javascript { .api }
121
/**
122
 * Get current line height
123
 * @param includeGap - Whether to include line gap in calculation
124
 * @returns Current line height in points
125
 */
126
currentLineHeight(includeGap?: boolean): number;
127

128
/**
129
 * Convert size value to points
130
 * @param size - Size value to convert
131
 * @param defaultValue - Default value if size is invalid
132
 * @param page - Page for percentage calculations (optional)
133
 * @param percentageWidth - Width for percentage calculations (optional)
134
 * @returns Size in points
135
 */
136
sizeToPoint(size: SizeValue, defaultValue?: number, page?: PDFPage, percentageWidth?: number): number;
137
```
138

139
**Usage Examples:**
140

141
```javascript
142
// Get line height for current font
143
const lineHeight = doc.currentLineHeight();
144
console.log(`Current line height: ${lineHeight}pt`);
145

146
// Include line gap in calculation
147
const lineHeightWithGap = doc.currentLineHeight(true);
148

149
// Convert different size units to points
150
const pointSize = doc.sizeToPoint('1em');      // Convert 1em to points
151
const pxSize = doc.sizeToPoint('16px');        // Convert 16px to points
152
const percentSize = doc.sizeToPoint('120%');   // Convert 120% to points
153

154
// Use in layout calculations
155
const spacing = doc.currentLineHeight() * 1.5;
156
doc.text('Line 1', 100, 100);
157
doc.text('Line 2', 100, 100 + spacing);
158
```
159

160
## Types
161

162
```javascript { .api }
163
type SizeValue = number | string;
164

165
// Supported size unit strings
166
type SizeUnit = 
167
  | 'pt'    // Points (default)
168
  | 'px'    // Pixels
169
  | 'em'    // Em units (relative to current font size)
170
  | 'rem'   // Root em units
171
  | 'in'    // Inches
172
  | 'cm'    // Centimeters  
173
  | 'mm'    // Millimeters
174
  | 'pc'    // Picas
175
  | 'ex'    // Ex units (x-height)
176
  | 'ch'    // Character units (0-width)
177
  | 'vw'    // Viewport width percentage
178
  | 'vh'    // Viewport height percentage
179
  | 'vmin'  // Viewport minimum dimension percentage
180
  | 'vmax'  // Viewport maximum dimension percentage
181
  | '%';    // Percentage
182

183
// Font source types
184
type FontSource = string | Buffer | ArrayBuffer;
185
```
186

187
## Font Loading Best Practices
188

189
### Custom Font Loading
190

191
```javascript
192
// Load multiple font weights/styles
193
doc.registerFont('Inter-Regular', './fonts/Inter-Regular.ttf')
194
   .registerFont('Inter-Bold', './fonts/Inter-Bold.ttf')
195
   .registerFont('Inter-Italic', './fonts/Inter-Italic.ttf');
196

197
// Use semantic naming
198
doc.registerFont('body', './fonts/source-sans-pro.ttf')
199
   .registerFont('heading', './fonts/playfair-display.ttf')
200
   .registerFont('code', './fonts/fira-code.ttf');
201
```
202

203
### Font Subsetting
204

205
PDFKit automatically subsets fonts to include only the glyphs used in the document, reducing file size:
206

207
```javascript
208
// Only characters used in the document will be included
209
doc.font('./fonts/large-font.ttf')
210
   .text('Only these characters will be embedded: Hello World!');
211
```
212

213
### Error Handling
214

215
```javascript
216
try {
217
  doc.font('./fonts/missing-font.ttf');
218
} catch (error) {
219
  console.error('Font loading failed:', error.message);
220
  // Fallback to built-in font
221
  doc.font('Helvetica');
222
}
223
```