0
# Text Rendering
1

2
Advanced text rendering with flexible positioning, styling, fonts, and layout options including line wrapping, multi-column support, and comprehensive typography controls.
3

4
## Capabilities
5

6
### Text Rendering
7

8
Core text rendering with extensive options for positioning, styling, and layout.
9

10
```javascript { .api }
11
/**
12
 * Render text with comprehensive options
13
 * @param text - Text to render
14
 * @param x - X coordinate (optional)
15
 * @param y - Y coordinate (optional)
16
 * @param options - Text rendering options
17
 * @returns Document instance for chaining
18
 */
19
text(text: string, x?: number, y?: number, options?: TextOptions): PDFDocument;
20

21
interface TextOptions {
22
  /** Text width for wrapping */
23
  width?: number;
24
  /** Maximum text height */
25
  height?: number;
26
  /** Text alignment */
27
  align?: 'left' | 'center' | 'right' | 'justify';
28
  /** Baseline alignment */
29
  baseline?: 'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom' | 'svg-middle' | 'svg-central' | 'mathematical' | number;
30
  /** Number of columns */
31
  columns?: number;
32
  /** Gap between columns */
33
  columnGap?: number;
34
  /** Text indent */
35
  indent?: number;
36
  /** Gap between paragraphs */
37
  paragraphGap?: number;
38
  /** Gap between lines */
39
  lineGap?: number;
40
  /** Extra word spacing */
41
  wordSpacing?: number;
42
  /** Extra character spacing */
43
  characterSpacing?: number;
44
  /** Horizontal text scaling (percentage) */
45
  horizontalScaling?: number;
46
  /** Enable text fill */
47
  fill?: boolean;
48
  /** Enable text stroke */
49
  stroke?: boolean;
50
  /** Text fill color */
51
  fillColor?: ColorValue;
52
  /** Text stroke color */
53
  strokeColor?: ColorValue;
54
  /** Add underline */
55
  underline?: boolean;
56
  /** Add strikethrough */
57
  strike?: boolean;
58
  /** Add hyperlink */
59
  link?: string;
60
  /** Add internal link */
61
  goTo?: string;
62
  /** Add named destination */
63
  destination?: string;
64
  /** Continue text on next call */
65
  continued?: boolean;
66
  /** OpenType font features */
67
  features?: string[];
68
  /** Text rotation in degrees */
69
  rotation?: number;
70
  /** Oblique text (skew angle or boolean) */
71
  oblique?: number | boolean;
72
}
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
// Basic text
79
doc.text('Hello World', 100, 100);
80

81
// Text with wrapping and alignment
82
doc.text('This is a long paragraph that will wrap to multiple lines within the specified width.', 100, 150, {
83
  width: 400,
84
  align: 'justify'
85
});
86

87
// Multi-column text
88
doc.text('Lorem ipsum...', 100, 200, {
89
  width: 400,
90
  columns: 2,
91
  columnGap: 20
92
});
93

94
// Styled text with effects
95
doc.text('Important Notice', 100, 300, {
96
  fill: true,
97
  fillColor: 'red',
98
  underline: true,
99
  fontSize: 18
100
});
101

102
// Text with hyperlink
103
doc.text('Visit our website', 100, 350, {
104
  link: 'https://example.com',
105
  fillColor: 'blue',
106
  underline: true
107
});
108
```
109

110
### Text Measurement
111

112
Methods for calculating text dimensions and layout.
113

114
```javascript { .api }
115
/**
116
 * Calculate the width of a string
117
 * @param string - String to measure
118
 * @param options - Text options affecting measurement
119
 * @returns Width in points
120
 */
121
widthOfString(string: string, options?: TextOptions): number;
122

123
/**
124
 * Calculate the height of text
125
 * @param text - Text to measure
126
 * @param options - Text options affecting measurement
127
 * @returns Height in points
128
 */
129
heightOfString(text: string, options?: TextOptions): number;
130

131
/**
132
 * Get bounding box of text
133
 * @param string - String to measure
134
 * @param x - X coordinate
135
 * @param y - Y coordinate
136
 * @param options - Text options
137
 * @returns Bounding box
138
 */
139
boundsOfString(string: string, x?: number, y?: number, options?: TextOptions): BoundingBox;
140

141
interface BoundingBox {
142
  x: number;
143
  y: number;
144
  width: number;
145
  height: number;
146
}
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
// Measure text for positioning
153
const text = 'Sample Text';
154
const width = doc.widthOfString(text);
155
const height = doc.heightOfString(text);
156

157
// Center text on page
158
const pageWidth = doc.page.width;
159
const centerX = (pageWidth - width) / 2;
160
doc.text(text, centerX, 100);
161

162
// Check if text fits in area
163
const maxWidth = 200;
164
if (doc.widthOfString('Long text content') > maxWidth) {
165
  // Use text wrapping
166
  doc.text('Long text content', 100, 100, { width: maxWidth });
167
}
168
```
169

170
### Font Management
171

172
Methods for managing fonts and font properties.
173

174
```javascript { .api }
175
/**
176
 * Set current font
177
 * @param src - Font source (path, Buffer, or font name)
178
 * @param family - Font family name
179
 * @param size - Font size
180
 * @returns Document instance for chaining
181
 */
182
font(src: string | Buffer, family?: string, size?: number): PDFDocument;
183

184
/**
185
 * Set font size with flexible units
186
 * @param size - Font size with optional units
187
 * @returns Document instance for chaining
188
 */
189
fontSize(size: SizeValue): PDFDocument;
190

191
/**
192
 * Register a font for later use
193
 * @param name - Font name for referencing
194
 * @param src - Font source
195
 * @param family - Font family name
196
 * @returns Document instance for chaining
197
 */
198
registerFont(name: string, src: string | Buffer, family?: string): PDFDocument;
199

200
/**
201
 * Get current line height
202
 * @param includeGap - Include line gap in calculation
203
 * @returns Line height in points
204
 */
205
currentLineHeight(includeGap?: boolean): number;
206

207
type SizeValue = number | `${number}` | `${number}${SizeUnit}`;
208
type SizeUnit = 'pt' | 'in' | 'px' | 'cm' | 'mm' | 'pc' | 'em' | 'ex' | 'ch' | 'rem' | 'vw' | 'vh' | 'vmin' | 'vmax' | '%';
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
// Use built-in fonts
215
doc.font('Helvetica', 12)
216
   .text('Standard font', 100, 100);
217

218
doc.font('Times-Bold', 16)
219
   .text('Bold serif font', 100, 120);
220

221
// Load custom font
222
doc.registerFont('MyFont', './fonts/custom.ttf');
223
doc.font('MyFont', 14)
224
   .text('Custom font text', 100, 140);
225

226
// Font size with units
227
doc.fontSize('14pt')
228
   .text('14 point text', 100, 160);
229

230
doc.fontSize('1.2em')
231
   .text('1.2em text', 100, 180);
232

233
// Get line height for spacing
234
const lineHeight = doc.currentLineHeight();
235
doc.text('Line 1', 100, 200)
236
   .text('Line 2', 100, 200 + lineHeight);
237
```
238

239
### Text Positioning
240

241
Methods for controlling text position and movement.
242

243
```javascript { .api }
244
/**
245
 * Move cursor down by specified number of lines
246
 * @param lines - Number of lines to move (default: 1)
247
 * @returns Document instance for chaining
248
 */
249
moveDown(lines?: number): PDFDocument;
250

251
/**
252
 * Move cursor up by specified number of lines
253
 * @param lines - Number of lines to move (default: 1)
254
 * @returns Document instance for chaining
255
 */
256
moveUp(lines?: number): PDFDocument;
257

258
/**
259
 * Set line gap for future text
260
 * @param gap - Gap between lines in points
261
 * @returns Document instance for chaining
262
 */
263
lineGap(gap: number): PDFDocument;
264
```
265

266
**Usage Examples:**
267

268
```javascript
269
doc.text('First line', 100, 100)
270
   .moveDown()
271
   .text('Second line (default spacing)')
272
   .moveDown(2)
273
   .text('Third line (double spacing)');
274

275
// Custom line gap
276
doc.lineGap(5)
277
   .text('Text with 5pt line gap', 100, 200)
278
   .moveDown()
279
   .text('Next line with same gap');
280
```
281

282
### List Rendering
283

284
Support for bulleted and numbered lists.
285

286
```javascript { .api }
287
/**
288
 * Render bulleted or numbered list
289
 * @param list - Array of list items
290
 * @param x - X coordinate
291
 * @param y - Y coordinate  
292
 * @param options - List options
293
 * @param wrapper - Text wrapper instance
294
 * @returns Document instance for chaining
295
 */
296
list(list: string[], x?: number, y?: number, options?: ListOptions, wrapper?: any): PDFDocument;
297

298
interface ListOptions extends TextOptions {
299
  /** List bullet character or numbering */
300
  bulletRadius?: number;
301
  /** Text indent for list items */
302
  textIndent?: number;
303
  /** Bullet indent */
304
  bulletIndent?: number;
305
}
306
```
307

308
**Usage Examples:**
309

310
```javascript
311
// Bulleted list
312
doc.list([
313
  'First item',
314
  'Second item',
315
  'Third item'
316
], 100, 100);
317

318
// Numbered list with custom options
319
doc.list([
320
  'Introduction',
321
  'Methods',
322
  'Results',
323
  'Conclusion'
324
], 100, 200, {
325
  textIndent: 20,
326
  bulletIndent: 10
327
});
328
```
329

330
### Size Conversion Utilities
331

332
Utilities for converting between different size units.
333

334
```javascript { .api }
335
/**
336
 * Convert size value to points
337
 * @param size - Size with optional units
338
 * @param defaultValue - Default value if size is invalid
339
 * @param page - Page context for percentage calculations
340
 * @param percentageWidth - Reference width for percentage
341
 * @returns Size in points
342
 */
343
sizeToPoint(size: SizeValue, defaultValue?: number, page?: any, percentageWidth?: number): number;
344
```
345

346
## Built-in Font Support
347

348
PDFKit includes built-in support for standard PDF fonts:
349

350
```javascript { .api }
351
// Standard fonts (no loading required)
352
type StandardFont = 
353
  | 'Courier' | 'Courier-Bold' | 'Courier-Oblique' | 'Courier-BoldOblique'
354
  | 'Helvetica' | 'Helvetica-Bold' | 'Helvetica-Oblique' | 'Helvetica-BoldOblique'  
355
  | 'Times-Roman' | 'Times-Bold' | 'Times-Italic' | 'Times-BoldItalic'
356
  | 'Symbol' | 'ZapfDingbats';
357
```
358

359
## Supported Font Formats
360

361
- **TrueType** (.ttf): Full support with subsetting
362
- **OpenType** (.otf): Full support with advanced typography features
363
- **WOFF/WOFF2** (.woff, .woff2): Web font support
364
- **TrueType Collections** (.ttc): Multiple fonts in single file
365
- **Datafork TrueType**: Legacy Mac format support
366

367
## Typography Features
368

369
- **Line wrapping** with soft hyphen recognition
370
- **Multi-column layout** with configurable gaps
371
- **Advanced alignment** including justify with proper word spacing
372
- **OpenType features** for advanced typography
373
- **Baseline control** for precise vertical positioning
374
- **Character and word spacing** adjustments
375
- **Text effects** including underline, strikethrough, rotation
376
- **Bidirectional text** support for RTL languages