CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pdfkit

A PDF generation library for Node.js with comprehensive text, graphics, and form support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

interactive-elements.mddocs/

Interactive Elements

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

Capabilities

General Annotations

Base annotation functionality for creating custom interactive elements.

/**
 * Create custom annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Annotation options
 * @returns Document instance for chaining
 */
annotate(x: number, y: number, w: number, h: number, options: AnnotationOptions): PDFDocument;

interface AnnotationOptions {
  /** Annotation type */
  Type?: string;
  /** Annotation subtype */
  Subtype?: string;
  /** Annotation contents */
  Contents?: string;
  /** Annotation color */
  C?: [number, number, number];
  /** Border style */
  Border?: [number, number, number];
  /** Annotation flags */
  F?: number;
}

Text Annotations

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

/**
 * Create text note annotation
 * @param x - X coordinate
 * @param y - Y coordinate  
 * @param w - Width
 * @param h - Height
 * @param contents - Note contents
 * @param options - Additional options
 * @returns Document instance for chaining
 */
note(x: number, y: number, w: number, h: number, contents: string, options?: TextAnnotationOptions): PDFDocument;

/**
 * Create free text annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param text - Text content
 * @param options - Text options
 * @returns Document instance for chaining
 */
textAnnotation(x: number, y: number, w: number, h: number, text: string, options?: FreeTextOptions): PDFDocument;

interface TextAnnotationOptions {
  /** Annotation color */
  color?: [number, number, number];
  /** Icon name */
  Name?: 'Comment' | 'Key' | 'Note' | 'Help' | 'NewParagraph' | 'Paragraph' | 'Insert';
  /** Open state */
  Open?: boolean;
}

interface FreeTextOptions {
  /** Text color */
  color?: [number, number, number];
  /** Font name */
  font?: string;
  /** Font size */
  fontSize?: number;
  /** Text alignment */
  alignment?: 'left' | 'center' | 'right';
}

Usage Examples:

// Sticky note
doc.note(100, 100, 20, 20, 'This is an important point to remember', {
  color: [255, 255, 0],  // Yellow
  Open: true
});

// Free text annotation
doc.textAnnotation(200, 100, 150, 30, 'Review this section', {
  color: [255, 0, 0],
  font: 'Helvetica',
  fontSize: 12,
  alignment: 'center'
});

Link Annotations

Hyperlinks and internal navigation links.

/**
 * Create hyperlink annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param url - Target URL
 * @param options - Link options
 * @returns Document instance for chaining
 */
link(x: number, y: number, w: number, h: number, url: string, options?: LinkOptions): PDFDocument;

/**
 * Create internal link annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param name - Destination name
 * @param options - Link options
 * @returns Document instance for chaining
 */
goTo(x: number, y: number, w: number, h: number, name: string, options?: LinkOptions): PDFDocument;

interface LinkOptions {
  /** Border color */
  color?: [number, number, number];
  /** Border width */
  borderWidth?: number;
  /** Highlight mode */
  highlight?: 'N' | 'I' | 'O' | 'P';
}

Usage Examples:

// External hyperlink
doc.link(100, 100, 200, 20, 'https://example.com', {
  color: [0, 0, 255],
  highlight: 'I'  // Invert colors when clicked
});

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

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

Markup Annotations

Visual markup annotations for highlighting and emphasis.

/**
 * Create highlight annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Highlight options
 * @returns Document instance for chaining
 */
highlight(x: number, y: number, w: number, h: number, options?: MarkupOptions): PDFDocument;

/**
 * Create underline annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Underline options
 * @returns Document instance for chaining
 */
underline(x: number, y: number, w: number, h: number, options?: MarkupOptions): PDFDocument;

/**
 * Create strikeout annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Strikeout options
 * @returns Document instance for chaining
 */
strike(x: number, y: number, w: number, h: number, options?: MarkupOptions): PDFDocument;

interface MarkupOptions {
  /** Annotation color */
  color?: [number, number, number];
  /** Opacity */
  opacity?: number;
  /** Contents/popup text */
  contents?: string;
}

Usage Examples:

// Highlight text
doc.highlight(100, 100, 200, 15, {
  color: [255, 255, 0],  // Yellow highlight
  opacity: 0.5,
  contents: 'Important information'
});

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

// Strike through text
doc.strike(100, 200, 180, 15, {
  color: [128, 128, 128], // Gray strikeout
  contents: 'Deleted text'
});

Geometric Annotations

Shape-based annotations for drawing attention.

/**
 * Create line annotation
 * @param x1 - Start X coordinate
 * @param y1 - Start Y coordinate
 * @param x2 - End X coordinate
 * @param y2 - End Y coordinate
 * @param options - Line options
 * @returns Document instance for chaining
 */
lineAnnotation(x1: number, y1: number, x2: number, y2: number, options?: LineAnnotationOptions): PDFDocument;

/**
 * Create rectangle annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Rectangle options
 * @returns Document instance for chaining
 */
rectAnnotation(x: number, y: number, w: number, h: number, options?: ShapeAnnotationOptions): PDFDocument;

/**
 * Create circle annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Circle options
 * @returns Document instance for chaining
 */
ellipseAnnotation(x: number, y: number, w: number, h: number, options?: ShapeAnnotationOptions): PDFDocument;

interface LineAnnotationOptions {
  /** Line color */
  color?: [number, number, number];
  /** Line width */
  borderWidth?: number;
  /** Line style */
  borderStyle?: 'S' | 'D' | 'B' | 'I' | 'U';
  /** Line ending styles */
  lineEndingStyles?: [string, string];
}

interface ShapeAnnotationOptions {
  /** Border color */
  color?: [number, number, number];
  /** Fill color */
  fillColor?: [number, number, number];
  /** Border width */
  borderWidth?: number;
  /** Border style */
  borderStyle?: 'S' | 'D' | 'B' | 'I' | 'U';
  /** Opacity */
  opacity?: number;
}

Usage Examples:

// Draw attention line
doc.lineAnnotation(100, 100, 200, 150, {
  color: [255, 0, 0],
  borderWidth: 2,
  lineEndingStyles: ['None', 'ClosedArrow']
});

// Highlight rectangle  
doc.rectAnnotation(100, 200, 150, 50, {
  color: [0, 0, 255],
  fillColor: [173, 216, 230],
  borderWidth: 1,
  opacity: 0.7
});

// Circle callout
doc.ellipseAnnotation(300, 100, 80, 80, {
  color: [255, 165, 0],
  borderWidth: 3
});

File Attachments

Embed files as annotations within the PDF.

/**
 * Create file attachment annotation
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param file - File path or buffer
 * @param options - Attachment options
 * @returns Document instance for chaining
 */
fileAnnotation(x: number, y: number, w: number, h: number, file?: string | Buffer, options?: FileAnnotationOptions): PDFDocument;

interface FileAnnotationOptions {
  /** Attachment icon */
  Name?: 'Graph' | 'PushPin' | 'Paperclip' | 'Tag';
  /** File description */
  contents?: string;
  /** File name override */
  name?: string;
}

Usage Examples:

// Attach document
doc.fileAnnotation(100, 100, 20, 20, './attachments/report.pdf', {
  Name: 'Paperclip',
  contents: 'Supporting documentation'
});

// Attach data file
const csvData = Buffer.from('Name,Age\nJohn,25\nJane,30', 'utf8');
doc.fileAnnotation(150, 100, 20, 20, csvData, {
  Name: 'Graph',
  contents: 'Data file',
  name: 'data.csv'
});

Interactive Forms

Create fillable PDF forms with various field types.

Form Initialization

/**
 * Initialize form support (required before creating form fields)
 * @returns Document instance for chaining
 */
initForm(): PDFDocument;

Form Field Creation

/**
 * Create form field container
 * @param name - Field name
 * @param options - Field options
 * @returns Document instance for chaining
 */
formField(name: string, options?: FormFieldOptions): PDFDocument;

/**
 * Create form widget annotation
 * @param name - Field name
 * @param type - Field type
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Widget options
 * @returns Document instance for chaining
 */
formAnnotation(name: string, type: string, x: number, y: number, w: number, h: number, options?: FormWidgetOptions): PDFDocument;

interface FormFieldOptions {
  /** Field flags */
  Ff?: number;
  /** Field value */
  V?: any;
  /** Default value */  
  DV?: any;
  /** Field type */
  FT?: 'Tx' | 'Ch' | 'Btn' | 'Sig';
}

interface FormWidgetOptions {
  /** Background color */
  backgroundColor?: [number, number, number];
  /** Border color */
  borderColor?: [number, number, number];
  /** Text color */
  textColor?: [number, number, number];
  /** Font size */
  fontSize?: number;
  /** Text alignment */
  textAlign?: 'left' | 'center' | 'right';
  /** Read-only flag */
  readOnly?: boolean;
  /** Required flag */
  required?: boolean;
}

Specific Form Field Types

/**
 * Create text input field
 * @param name - Field name
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Text field options
 * @returns Document instance for chaining
 */
formText(name: string, x: number, y: number, w: number, h: number, options?: TextFieldOptions): PDFDocument;

/**
 * Create push button
 * @param name - Button name
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Button options
 * @returns Document instance for chaining
 */
formPushButton(name: string, x: number, y: number, w: number, h: number, options?: ButtonOptions): PDFDocument;

/**
 * Create combo box (dropdown)
 * @param name - Field name
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Combo box options
 * @returns Document instance for chaining
 */
formCombo(name: string, x: number, y: number, w: number, h: number, options?: ChoiceFieldOptions): PDFDocument;

/**
 * Create list box
 * @param name - Field name
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - List box options
 * @returns Document instance for chaining
 */
formList(name: string, x: number, y: number, w: number, h: number, options?: ChoiceFieldOptions): PDFDocument;

/**
 * Create radio button
 * @param name - Group name
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Radio button options
 * @returns Document instance for chaining
 */
formRadioButton(name: string, x: number, y: number, w: number, h: number, options?: RadioButtonOptions): PDFDocument;

/**
 * Create checkbox
 * @param name - Field name
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param w - Width
 * @param h - Height
 * @param options - Checkbox options
 * @returns Document instance for chaining
 */
formCheckbox(name: string, x: number, y: number, w: number, h: number, options?: CheckboxOptions): PDFDocument;

interface TextFieldOptions extends FormWidgetOptions {
  /** Multiline text */
  multiline?: boolean;
  /** Password field */
  password?: boolean;
  /** Maximum length */
  maxLength?: number;
  /** Default value */
  value?: string;
}

interface ButtonOptions extends FormWidgetOptions {
  /** Button label */
  label?: string;
  /** JavaScript action */
  action?: string;
}

interface ChoiceFieldOptions extends FormWidgetOptions {
  /** Choice options */
  select?: string[];
  /** Allow editing (combo only) */
  edit?: boolean;
  /** Allow multiple selection */
  multiSelect?: boolean;
  /** Selected values */
  value?: string | string[];
}

interface RadioButtonOptions extends FormWidgetOptions {
  /** Button value */
  value?: string;
  /** Group value */
  groupValue?: string;
}

interface CheckboxOptions extends FormWidgetOptions {
  /** Checked state */
  checked?: boolean;
}

Usage Examples:

// Initialize form
doc.initForm();

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

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

// Checkbox
doc.formCheckbox('newsletter', 100, 300, 15, 15, {
  checked: true
});

// Radio buttons (same group name)
doc.formRadioButton('gender', 100, 250, 15, 15, {
  value: 'male'
});
doc.formRadioButton('gender', 150, 250, 15, 15, {
  value: 'female'
});

// Submit button
doc.formPushButton('submit', 100, 200, 80, 30, {
  label: 'Submit',
  backgroundColor: [0, 128, 255],
  textColor: [255, 255, 255]
});

Interactive Features

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

Install with Tessl CLI

npx tessl i tessl/npm-pdfkit

docs

accessibility-features.md

attachments.md

color-management.md

document-management.md

font-management.md

image-handling.md

index.md

interactive-elements.md

outline.md

tables.md

text-rendering.md

vector-graphics.md

tile.json