How to Work with PDF Attachments in TypeScript

This guide shows how to work with file attachments in PDF documents with Aspose.PDF FOSS for TypeScript. Document.AddAttachment() embeds a file at the document level; Page.AddFileAttachment() places a clickable paperclip-style annotation on a page that opens an embedded file. It requires Node.js 22 or later.

Step-by-Step Guide

Step 1: Install the Package

asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.

Verify the installation by importing the Document class in a new TypeScript file — this line should resolve without error once the package is installed:

import { Document } from '@asposefoss/pdf';

Step 2: Import Required Classes

Import Document to open the file and reach both attachment entry points used below:

import { Document } from '@asposefoss/pdf';

Step 3: Open the Target Document

Both attachment methods are called on an open Document — Page-level attachments additionally need the target Page:

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

Step 4: Embed a Document-Level Attachment

Document.AddAttachment(name, bytes, opts) -> Attachment embeds a file into the document’s collection of embedded files, keyed by name. Document.GetAttachments() -> Attachment[] lists everything currently embedded, and Document.RemoveAttachment(name) -> boolean removes one by name.

Step 5: Add a Page-Level File Attachment Annotation

Page.AddFileAttachment(opts) -> FileAttachmentAnnotation places a clickable icon on the page — similar to the sticky-note and free-text annotations covered in the Annotations guide — that a viewer opens to save or preview the embedded file. Unlike Document.AddAttachment(), it is anchored to a specific page location rather than listed only in the document’s embedded-files collection.

Common Issues and Fixes

An attachment added with Document.AddAttachment() has no visible icon on any page. This is expected — a document-level attachment lives in the embedded-files collection, not on a page. Use Page.AddFileAttachment() in addition if a clickable icon on a specific page is required.

Document.RemoveAttachment() returns false. It returns false when no attachment is registered under the given name — list the current set with Document.GetAttachments() first to confirm the exact name in use.

Two attachments were embedded under the same name. name in Document.AddAttachment() is the key used to look the attachment back up with RemoveAttachment() — reusing a name for a second call can shadow or conflict with the first, depending on how the viewer resolves duplicates. Use a distinct name per embedded file.

Frequently Asked Questions

What is the difference between a document-level and a page-level attachment?

A document-level attachment (Document.AddAttachment()) lives in the PDF’s embedded-files collection and is not tied to any page. A page-level attachment (Page.AddFileAttachment()) is an annotation anchored to a specific page location, similar to a sticky note.

How do I see what is currently embedded in a document?

Call Document.GetAttachments(), which returns every currently embedded Attachment.

Can an attachment be removed after it is added?

Yes — Document.RemoveAttachment(name) removes a document-level attachment by the name it was added under, and returns true if it found and removed one.