Build a JavaScript PDF Watermark Tool That Runs Entirely in the Browser

PDF watermarks are essential for branding, document security, approvals, confidential files, and internal tracking. Whether you need to stamp a company logo, mark a file as “CONFIDENTIAL,” or label a draft version, you often want a quick solution that doesn’t require uploading sensitive documents to external servers. Modern browsers make this possible with JavaScript libraries that handle PDF processing client-side. This approach keeps files private, speeds up workflows, and eliminates backend dependencies.

In this tutorial, you’ll learn how to create a browser-based PDF watermark tool using JavaScript. The tool supports both text and image watermarks, adjustable opacity, rotation, page selection, positioning controls, and direct PDF download—all from the browser without a server.

How PDF Watermarking Works

A PDF watermark is simply an overlay—text or an image—placed on top of an existing PDF page. In the browser, JavaScript libraries can load PDF files, modify their visual layers, and export a new version. The process begins when a user uploads a PDF. JavaScript reads the document, loads each page, and applies watermark elements (text or logos) on top of the original content. After adjusting position and opacity, the updated PDF is generated and downloaded. Everything takes place locally on the user’s device, improving privacy and security.

Build a JavaScript PDF Watermark Tool That Runs Entirely in the Browser — Source: www.freecodecamp.org

Setting Up the Project

This project is intentionally simple. No backend is required—just an HTML file, a JavaScript file, and a PDF processing library.

Choosing a Library

We’ll use PDF-lib, a JavaScript library designed for editing PDFs directly in the browser. It allows loading existing documents, modifying pages, inserting custom text or image watermarks, and exporting the final PDF. Include it via CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

Because everything runs client-side, users can edit PDFs without uploading files to any server.

Building the Upload Interface

Start with a simple file input and a button to trigger watermarking:

<input type="file" id="pdfUpload" accept="application/pdf">
<button onclick="applyWatermark()">Apply Watermark</button>

This lets users select a PDF file from their device. When the button is clicked, the applyWatermark() function will read the file and begin processing.

Adding Text and Image Watermarks

PDF-lib provides methods to draw text and embed images onto existing pages. For text watermarks, you can set the font, size, color, and rotation. For image watermarks (like a logo), you first load the image data (PNG/JPEG), embed it into the PDF, and then place it at desired coordinates.

Example workflow for a text watermark:

Load the existing PDF using PDFDocument.load().
Get the target page(s) with pdfDoc.getPage(index).
Use page.drawText() with options for position, size, color, opacity, and rotation.

For an image watermark, use pdfDoc.embedPng() or pdfDoc.embedJpg() and then page.drawImage().

Controlling Position, Opacity, and Page Selection

To make the tool flexible, add UI controls for:

Position: X and Y coordinates (in PDF units) or preset positions like top-left, center, bottom-right.
Opacity: A slider (0 to 1) that sets the alpha value of the watermark.
Rotation: Degrees to rotate the watermark (e.g., 45° for a diagonal stamp).
Page selection: Checkboxes or a range input to apply watermarks only to specific pages (e.g., all, first, last, or custom range).

These controls modify the parameters passed to PDF-lib’s drawing functions, allowing users to fine-tune the result.

Generating and Downloading the Final PDF

After applying the watermark, save the modified document using pdfDoc.save(), which returns a Uint8Array. Convert it to a Blob and trigger a download:

const pdfBytes = await pdfDoc.save();
const blob = new Blob([pdfBytes], { type: 'application/pdf' });
const url = URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = url;
link.download = 'watermarked.pdf';
link.click();

The user now has a watermarked PDF saved locally, without any data leaving their machine.

Tips and Common Pitfalls

Real-World Considerations

Font availability: PDF-lib includes only a few built-in fonts (Helvetica, Times, Courier). For custom fonts, embed them as Uint8Array.
Image size: Large images can bloat the PDF. Resize images before embedding if needed.
Page dimensions: PDF-lib uses standard page sizes. Always check the page’s width and height to position watermarks correctly.
Existing PDF structure: Some PDFs (with forms or complex annotations) may not render watermarks as expected. Test with various documents.

Common Mistakes to Avoid

Forgetting to load the PDF in a valid array buffer—use FileReader to convert the uploaded file.
Applying watermarks outside page boundaries—always calculate coordinates relative to page dimensions.
Not handling errors during PDF loading—wrap operations in try/catch blocks.
Using opacity values outside 0–1 range—PDF-lib expects a number between 0 and 1.

Conclusion

You now have the knowledge to build a fully functional, client-side PDF watermark tool with JavaScript. By leveraging PDF-lib and the browser’s native APIs, you can offer users a private, fast, and zero-dependency solution for adding watermarks to their documents. The complete tool—from file upload to download—runs entirely on the client, ensuring data never leaves the device. Experiment with additional features like multiple watermarks, opacity presets, or image scaling to further enhance the tool.

Fbhchile