0
# Interactive Elements
1

2
Annotations, hyperlinks, form fields, and interactive PDF features for creating engaging and functional documents.
3

4
## Capabilities
5

6
### General Annotations
7

8
Base annotation functionality for creating custom interactive elements.
9

10
```javascript { .api }
11
/**
12
 * Create custom annotation
13
 * @param x - X coordinate
14
 * @param y - Y coordinate
15
 * @param w - Width
16
 * @param h - Height
17
 * @param options - Annotation options
18
 * @returns Document instance for chaining
19
 */
20
annotate(x: number, y: number, w: number, h: number, options: AnnotationOptions): PDFDocument;
21

22
interface AnnotationOptions {
23
  /** Annotation type */
24
  Type?: string;
25
  /** Annotation subtype */
26
  Subtype?: string;
27
  /** Annotation contents */
28
  Contents?: string;
29
  /** Annotation color */
30
  C?: [number, number, number];
31
  /** Border style */
32
  Border?: [number, number, number];
33
  /** Annotation flags */
34
  F?: number;
35
}
36
```
37

38
### Text Annotations
39

40
Note and text-based annotations for document review and commentary.
41

42
```javascript { .api }
43
/**
44
 * Create text note annotation
45
 * @param x - X coordinate
46
 * @param y - Y coordinate  
47
 * @param w - Width
48
 * @param h - Height
49
 * @param contents - Note contents
50
 * @param options - Additional options
51
 * @returns Document instance for chaining
52
 */
53
note(x: number, y: number, w: number, h: number, contents: string, options?: TextAnnotationOptions): PDFDocument;
54

55
/**
56
 * Create free text annotation
57
 * @param x - X coordinate
58
 * @param y - Y coordinate
59
 * @param w - Width
60
 * @param h - Height
61
 * @param text - Text content
62
 * @param options - Text options
63
 * @returns Document instance for chaining
64
 */
65
textAnnotation(x: number, y: number, w: number, h: number, text: string, options?: FreeTextOptions): PDFDocument;
66

67
interface TextAnnotationOptions {
68
  /** Annotation color */
69
  color?: [number, number, number];
70
  /** Icon name */
71
  Name?: 'Comment' | 'Key' | 'Note' | 'Help' | 'NewParagraph' | 'Paragraph' | 'Insert';
72
  /** Open state */
73
  Open?: boolean;
74
}
75

76
interface FreeTextOptions {
77
  /** Text color */
78
  color?: [number, number, number];
79
  /** Font name */
80
  font?: string;
81
  /** Font size */
82
  fontSize?: number;
83
  /** Text alignment */
84
  alignment?: 'left' | 'center' | 'right';
85
}
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
// Sticky note
92
doc.note(100, 100, 20, 20, 'This is an important point to remember', {
93
  color: [255, 255, 0],  // Yellow
94
  Open: true
95
});
96

97
// Free text annotation
98
doc.textAnnotation(200, 100, 150, 30, 'Review this section', {
99
  color: [255, 0, 0],
100
  font: 'Helvetica',
101
  fontSize: 12,
102
  alignment: 'center'
103
});
104
```
105

106
### Link Annotations
107

108
Hyperlinks and internal navigation links.
109

110
```javascript { .api }
111
/**
112
 * Create hyperlink annotation
113
 * @param x - X coordinate
114
 * @param y - Y coordinate
115
 * @param w - Width
116
 * @param h - Height
117
 * @param url - Target URL
118
 * @param options - Link options
119
 * @returns Document instance for chaining
120
 */
121
link(x: number, y: number, w: number, h: number, url: string, options?: LinkOptions): PDFDocument;
122

123
/**
124
 * Create internal link annotation
125
 * @param x - X coordinate
126
 * @param y - Y coordinate
127
 * @param w - Width
128
 * @param h - Height
129
 * @param name - Destination name
130
 * @param options - Link options
131
 * @returns Document instance for chaining
132
 */
133
goTo(x: number, y: number, w: number, h: number, name: string, options?: LinkOptions): PDFDocument;
134

135
interface LinkOptions {
136
  /** Border color */
137
  color?: [number, number, number];
138
  /** Border width */
139
  borderWidth?: number;
140
  /** Highlight mode */
141
  highlight?: 'N' | 'I' | 'O' | 'P';
142
}
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
// External hyperlink
149
doc.link(100, 100, 200, 20, 'https://example.com', {
150
  color: [0, 0, 255],
151
  highlight: 'I'  // Invert colors when clicked
152
});
153

154
// Internal link to named destination
155
doc.goTo(100, 150, 150, 20, 'chapter2', {
156
  color: [0, 128, 0]
157
});
158

159
// Named destination (target for internal links)
160
doc.addNamedDestination('chapter2', 'XYZ', 100, 400, 0);
161
```
162

163
### Markup Annotations
164

165
Visual markup annotations for highlighting and emphasis.
166

167
```javascript { .api }
168
/**
169
 * Create highlight annotation
170
 * @param x - X coordinate
171
 * @param y - Y coordinate
172
 * @param w - Width
173
 * @param h - Height
174
 * @param options - Highlight options
175
 * @returns Document instance for chaining
176
 */
177
highlight(x: number, y: number, w: number, h: number, options?: MarkupOptions): PDFDocument;
178

179
/**
180
 * Create underline annotation
181
 * @param x - X coordinate
182
 * @param y - Y coordinate
183
 * @param w - Width
184
 * @param h - Height
185
 * @param options - Underline options
186
 * @returns Document instance for chaining
187
 */
188
underline(x: number, y: number, w: number, h: number, options?: MarkupOptions): PDFDocument;
189

190
/**
191
 * Create strikeout annotation
192
 * @param x - X coordinate
193
 * @param y - Y coordinate
194
 * @param w - Width
195
 * @param h - Height
196
 * @param options - Strikeout options
197
 * @returns Document instance for chaining
198
 */
199
strike(x: number, y: number, w: number, h: number, options?: MarkupOptions): PDFDocument;
200

201
interface MarkupOptions {
202
  /** Annotation color */
203
  color?: [number, number, number];
204
  /** Opacity */
205
  opacity?: number;
206
  /** Contents/popup text */
207
  contents?: string;
208
}
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
// Highlight text
215
doc.highlight(100, 100, 200, 15, {
216
  color: [255, 255, 0],  // Yellow highlight
217
  opacity: 0.5,
218
  contents: 'Important information'
219
});
220

221
// Underline text
222
doc.underline(100, 150, 150, 15, {
223
  color: [255, 0, 0],    // Red underline
224
  contents: 'Key term'
225
});
226

227
// Strike through text
228
doc.strike(100, 200, 180, 15, {
229
  color: [128, 128, 128], // Gray strikeout
230
  contents: 'Deleted text'
231
});
232
```
233

234
### Geometric Annotations
235

236
Shape-based annotations for drawing attention.
237

238
```javascript { .api }
239
/**
240
 * Create line annotation
241
 * @param x1 - Start X coordinate
242
 * @param y1 - Start Y coordinate
243
 * @param x2 - End X coordinate
244
 * @param y2 - End Y coordinate
245
 * @param options - Line options
246
 * @returns Document instance for chaining
247
 */
248
lineAnnotation(x1: number, y1: number, x2: number, y2: number, options?: LineAnnotationOptions): PDFDocument;
249

250
/**
251
 * Create rectangle annotation
252
 * @param x - X coordinate
253
 * @param y - Y coordinate
254
 * @param w - Width
255
 * @param h - Height
256
 * @param options - Rectangle options
257
 * @returns Document instance for chaining
258
 */
259
rectAnnotation(x: number, y: number, w: number, h: number, options?: ShapeAnnotationOptions): PDFDocument;
260

261
/**
262
 * Create circle annotation
263
 * @param x - X coordinate
264
 * @param y - Y coordinate
265
 * @param w - Width
266
 * @param h - Height
267
 * @param options - Circle options
268
 * @returns Document instance for chaining
269
 */
270
ellipseAnnotation(x: number, y: number, w: number, h: number, options?: ShapeAnnotationOptions): PDFDocument;
271

272
interface LineAnnotationOptions {
273
  /** Line color */
274
  color?: [number, number, number];
275
  /** Line width */
276
  borderWidth?: number;
277
  /** Line style */
278
  borderStyle?: 'S' | 'D' | 'B' | 'I' | 'U';
279
  /** Line ending styles */
280
  lineEndingStyles?: [string, string];
281
}
282

283
interface ShapeAnnotationOptions {
284
  /** Border color */
285
  color?: [number, number, number];
286
  /** Fill color */
287
  fillColor?: [number, number, number];
288
  /** Border width */
289
  borderWidth?: number;
290
  /** Border style */
291
  borderStyle?: 'S' | 'D' | 'B' | 'I' | 'U';
292
  /** Opacity */
293
  opacity?: number;
294
}
295
```
296

297
**Usage Examples:**
298

299
```javascript
300
// Draw attention line
301
doc.lineAnnotation(100, 100, 200, 150, {
302
  color: [255, 0, 0],
303
  borderWidth: 2,
304
  lineEndingStyles: ['None', 'ClosedArrow']
305
});
306

307
// Highlight rectangle  
308
doc.rectAnnotation(100, 200, 150, 50, {
309
  color: [0, 0, 255],
310
  fillColor: [173, 216, 230],
311
  borderWidth: 1,
312
  opacity: 0.7
313
});
314

315
// Circle callout
316
doc.ellipseAnnotation(300, 100, 80, 80, {
317
  color: [255, 165, 0],
318
  borderWidth: 3
319
});
320
```
321

322
### File Attachments
323

324
Embed files as annotations within the PDF.
325

326
```javascript { .api }
327
/**
328
 * Create file attachment annotation
329
 * @param x - X coordinate
330
 * @param y - Y coordinate
331
 * @param w - Width
332
 * @param h - Height
333
 * @param file - File path or buffer
334
 * @param options - Attachment options
335
 * @returns Document instance for chaining
336
 */
337
fileAnnotation(x: number, y: number, w: number, h: number, file?: string | Buffer, options?: FileAnnotationOptions): PDFDocument;
338

339
interface FileAnnotationOptions {
340
  /** Attachment icon */
341
  Name?: 'Graph' | 'PushPin' | 'Paperclip' | 'Tag';
342
  /** File description */
343
  contents?: string;
344
  /** File name override */
345
  name?: string;
346
}
347
```
348

349
**Usage Examples:**
350

351
```javascript
352
// Attach document
353
doc.fileAnnotation(100, 100, 20, 20, './attachments/report.pdf', {
354
  Name: 'Paperclip',
355
  contents: 'Supporting documentation'
356
});
357

358
// Attach data file
359
const csvData = Buffer.from('Name,Age\nJohn,25\nJane,30', 'utf8');
360
doc.fileAnnotation(150, 100, 20, 20, csvData, {
361
  Name: 'Graph',
362
  contents: 'Data file',
363
  name: 'data.csv'
364
});
365
```
366

367
## Interactive Forms
368

369
Create fillable PDF forms with various field types.
370

371
### Form Initialization
372

373
```javascript { .api }
374
/**
375
 * Initialize form support (required before creating form fields)
376
 * @returns Document instance for chaining
377
 */
378
initForm(): PDFDocument;
379
```
380

381
### Form Field Creation
382

383
```javascript { .api }
384
/**
385
 * Create form field container
386
 * @param name - Field name
387
 * @param options - Field options
388
 * @returns Document instance for chaining
389
 */
390
formField(name: string, options?: FormFieldOptions): PDFDocument;
391

392
/**
393
 * Create form widget annotation
394
 * @param name - Field name
395
 * @param type - Field type
396
 * @param x - X coordinate
397
 * @param y - Y coordinate
398
 * @param w - Width
399
 * @param h - Height
400
 * @param options - Widget options
401
 * @returns Document instance for chaining
402
 */
403
formAnnotation(name: string, type: string, x: number, y: number, w: number, h: number, options?: FormWidgetOptions): PDFDocument;
404

405
interface FormFieldOptions {
406
  /** Field flags */
407
  Ff?: number;
408
  /** Field value */
409
  V?: any;
410
  /** Default value */  
411
  DV?: any;
412
  /** Field type */
413
  FT?: 'Tx' | 'Ch' | 'Btn' | 'Sig';
414
}
415

416
interface FormWidgetOptions {
417
  /** Background color */
418
  backgroundColor?: [number, number, number];
419
  /** Border color */
420
  borderColor?: [number, number, number];
421
  /** Text color */
422
  textColor?: [number, number, number];
423
  /** Font size */
424
  fontSize?: number;
425
  /** Text alignment */
426
  textAlign?: 'left' | 'center' | 'right';
427
  /** Read-only flag */
428
  readOnly?: boolean;
429
  /** Required flag */
430
  required?: boolean;
431
}
432
```
433

434
### Specific Form Field Types
435

436
```javascript { .api }
437
/**
438
 * Create text input field
439
 * @param name - Field name
440
 * @param x - X coordinate
441
 * @param y - Y coordinate
442
 * @param w - Width
443
 * @param h - Height
444
 * @param options - Text field options
445
 * @returns Document instance for chaining
446
 */
447
formText(name: string, x: number, y: number, w: number, h: number, options?: TextFieldOptions): PDFDocument;
448

449
/**
450
 * Create push button
451
 * @param name - Button name
452
 * @param x - X coordinate
453
 * @param y - Y coordinate
454
 * @param w - Width
455
 * @param h - Height
456
 * @param options - Button options
457
 * @returns Document instance for chaining
458
 */
459
formPushButton(name: string, x: number, y: number, w: number, h: number, options?: ButtonOptions): PDFDocument;
460

461
/**
462
 * Create combo box (dropdown)
463
 * @param name - Field name
464
 * @param x - X coordinate
465
 * @param y - Y coordinate
466
 * @param w - Width
467
 * @param h - Height
468
 * @param options - Combo box options
469
 * @returns Document instance for chaining
470
 */
471
formCombo(name: string, x: number, y: number, w: number, h: number, options?: ChoiceFieldOptions): PDFDocument;
472

473
/**
474
 * Create list box
475
 * @param name - Field name
476
 * @param x - X coordinate
477
 * @param y - Y coordinate
478
 * @param w - Width
479
 * @param h - Height
480
 * @param options - List box options
481
 * @returns Document instance for chaining
482
 */
483
formList(name: string, x: number, y: number, w: number, h: number, options?: ChoiceFieldOptions): PDFDocument;
484

485
/**
486
 * Create radio button
487
 * @param name - Group name
488
 * @param x - X coordinate
489
 * @param y - Y coordinate
490
 * @param w - Width
491
 * @param h - Height
492
 * @param options - Radio button options
493
 * @returns Document instance for chaining
494
 */
495
formRadioButton(name: string, x: number, y: number, w: number, h: number, options?: RadioButtonOptions): PDFDocument;
496

497
/**
498
 * Create checkbox
499
 * @param name - Field name
500
 * @param x - X coordinate
501
 * @param y - Y coordinate
502
 * @param w - Width
503
 * @param h - Height
504
 * @param options - Checkbox options
505
 * @returns Document instance for chaining
506
 */
507
formCheckbox(name: string, x: number, y: number, w: number, h: number, options?: CheckboxOptions): PDFDocument;
508

509
interface TextFieldOptions extends FormWidgetOptions {
510
  /** Multiline text */
511
  multiline?: boolean;
512
  /** Password field */
513
  password?: boolean;
514
  /** Maximum length */
515
  maxLength?: number;
516
  /** Default value */
517
  value?: string;
518
}
519

520
interface ButtonOptions extends FormWidgetOptions {
521
  /** Button label */
522
  label?: string;
523
  /** JavaScript action */
524
  action?: string;
525
}
526

527
interface ChoiceFieldOptions extends FormWidgetOptions {
528
  /** Choice options */
529
  select?: string[];
530
  /** Allow editing (combo only) */
531
  edit?: boolean;
532
  /** Allow multiple selection */
533
  multiSelect?: boolean;
534
  /** Selected values */
535
  value?: string | string[];
536
}
537

538
interface RadioButtonOptions extends FormWidgetOptions {
539
  /** Button value */
540
  value?: string;
541
  /** Group value */
542
  groupValue?: string;
543
}
544

545
interface CheckboxOptions extends FormWidgetOptions {
546
  /** Checked state */
547
  checked?: boolean;
548
}
549
```
550

551
**Usage Examples:**
552

553
```javascript
554
// Initialize form
555
doc.initForm();
556

557
// Text input
558
doc.formText('firstName', 100, 400, 200, 25, {
559
  backgroundColor: [240, 240, 240],
560
  fontSize: 12,
561
  value: 'Enter name...'
562
});
563

564
// Dropdown
565
doc.formCombo('country', 100, 350, 150, 25, {
566
  select: ['USA', 'Canada', 'Mexico'],
567
  value: 'USA'
568
});
569

570
// Checkbox
571
doc.formCheckbox('newsletter', 100, 300, 15, 15, {
572
  checked: true
573
});
574

575
// Radio buttons (same group name)
576
doc.formRadioButton('gender', 100, 250, 15, 15, {
577
  value: 'male'
578
});
579
doc.formRadioButton('gender', 150, 250, 15, 15, {
580
  value: 'female'
581
});
582

583
// Submit button
584
doc.formPushButton('submit', 100, 200, 80, 30, {
585
  label: 'Submit',
586
  backgroundColor: [0, 128, 255],
587
  textColor: [255, 255, 255]
588
});
589
```
590

591
## Interactive Features
592

593
- **Annotation Layers**: Annotations appear above content
594
- **Form Validation**: Client-side JavaScript validation support
595
- **Accessibility**: Screen reader compatible when properly tagged
596
- **Print Behavior**: Control whether annotations print
597
- **Export Values**: Define values exported from form fields
598
- **Tab Order**: Control field navigation order