How to Add Background and Overlay Foreground on PDFs in Java

Updated: August 2, 2026

IronPDF for Java provides addBackgroundPdf and addForegroundPdf methods that place additional PDF content either behind or on top of existing pages. These methods cover the full range of practical overlay scenarios: letterheads, color fills, watermarks, approval stamps, and revision indicators. The library renders HTML to PDF internally, so any valid CSS expression (gradients, images, typography) can become a background or foreground layer without manual PDF stream manipulation.

Add IronPDF to your project by declaring the dependency in pom.xml via Maven Central, then activate your license key before making any API calls.

Quickstart: Add Background and Foreground to PDFs

1Install IronPDF with Maven Central Repository

> mvn install

<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2026.8.2</version>
</dependency>

2Copy and run this code snippet.

:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/quickstart.java

:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/quickstart.java

Java

3Deploy to test on your live environment

Start using IronPDF in your project today with a free trial

Minimal Workflow (5 steps)

Install the IronPDF Java library via Maven
Load the target PDF with PdfDocument.fromFile()
Render or import the background or foreground PDF
Call addBackgroundPdf to layer content behind existing pages
Call addForegroundPdf to overlay content on top of existing pages

How Do I Add a Background to a PDF?

To add a background to an existing PDF, call addBackgroundPdf on a PdfDocument instance and pass a second PdfDocument as the background source. The method composites the background beneath every page of the target document. Before running the code, set up IronPDF with your license key to activate the library.

import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import java.nio.file.Paths;

// Activate the license
License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Render a background from an HTML color definition
PdfDocument background = PdfDocument.renderHtmlAsPdf("<body style='background-color: cyan;'></body>");

// Apply the background to all pages
pdf.addBackgroundPdf(background);

pdf.saveAs(Paths.get("addBackground.pdf"));

import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import java.nio.file.Paths;

// Activate the license
License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Render a background from an HTML color definition
PdfDocument background = PdfDocument.renderHtmlAsPdf("<body style='background-color: cyan;'></body>");

// Apply the background to all pages
pdf.addBackgroundPdf(background);

pdf.saveAs(Paths.get("addBackground.pdf"));

Java

The renderHtmlAsPdf call converts any valid HTML and CSS into a PDF page that IronPDF composites behind your existing content. You can use custom CSS styling in the HTML to PDF tutorial to produce gradient fills, repeating patterns, or image-based backgrounds. The HTML rendering engine processes modern CSS properties, so designs that work in a browser translate directly into the background layer.

Tips: Use <body style='margin:0; padding:0;'> in your HTML background template to eliminate default browser margins and ensure the color or image fills the entire page.

What Does the Background Output PDF Look Like?

Why Use HTML to Create PDF Backgrounds?

Adding a background layers an image or document page behind existing content, enabling letterheads, color fills, watermarks, and decorative design elements. Overlaying a foreground places content on top, making it useful for annotations, stamps, and approval indicators.

The HTML-based approach offers several concrete advantages over image imports:

Precise CSS control: Use any CSS color, gradient, image, or layout to define the background design.
Page-size adaptability: Backgrounds rendered from HTML scale to match the target PDF page dimensions automatically.
Dynamic generation: Build backgrounds programmatically from data, user preferences, or template logic.
Lightweight output: CSS-defined backgrounds are smaller than raster images at equivalent visual quality.

This functionality suits creating forms with company letterheads or adding custom watermarks to legal and financial documents.

How Do I Add a Background to Specific Pages?

The addBackgroundPdf method accepts an optional PageSelection argument that limits the operation to the pages you specify. Use PageSelection.firstPage(), PageSelection.lastPage(), PageSelection.singlePage(int index), or PageSelection.pageRange(int start, int end) to target any subset of pages. Full PageSelection documentation is available in the IronPDF for Java API Reference.

import com.ironsoftware.ironpdf.*;
import com.ironsoftware.ironpdf.edit.PageSelection;
import java.nio.file.Paths;

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Load a background from an existing PDF file
PdfDocument background = PdfDocument.fromFile(Paths.get("background.pdf"));

// Apply only the first page of the background PDF to the first page of the target
pdf.addBackgroundPdf(background, 0, PageSelection.firstPage());

pdf.saveAs(Paths.get("addBackgroundToSpecificPage.pdf"));

import com.ironsoftware.ironpdf.*;
import com.ironsoftware.ironpdf.edit.PageSelection;
import java.nio.file.Paths;

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Load a background from an existing PDF file
PdfDocument background = PdfDocument.fromFile(Paths.get("background.pdf"));

// Apply only the first page of the background PDF to the first page of the target
pdf.addBackgroundPdf(background, 0, PageSelection.firstPage());

pdf.saveAs(Paths.get("addBackgroundToSpecificPage.pdf"));

Java

The second argument (0) is the backgroundPdfPageIndex, a zero-based index that selects which page of the background PDF to use as the source. When your background template contains multiple page designs, this parameter lets you apply different designs to different sections of the target document. Combine selective backgrounds with PDF splitting and merging examples to build multi-stage document assembly workflows.

When Should You Apply Backgrounds to Specific Pages?

Selective background application covers a range of common document scenarios:

Cover pages: Brand the first page with a full-bleed design while keeping body pages clean.
Chapter dividers: Apply section backgrounds to the first page of each chapter.
Legal authentication: Add an official letterhead only to pages requiring formal certification.
Confidential sections: Tint or mark specific pages to indicate restricted content.
Print-ready layouts: Apply bleed-safe backgrounds to pages destined for physical printing.

After applying high-resolution background images, consider compressing the output PDF to keep file sizes manageable for distribution or archiving.

How Do I Add a Foreground Overlay to a PDF?

The addForegroundPdf method composites a PDF layer on top of existing page content. The rendered foreground appears above all existing text, images, and graphics on each target page. This method is the standard approach for watermarks, approval stamps, and revision indicators that must remain visible regardless of the underlying content. For working code samples, see the backgrounds and foregrounds Java examples.

import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import java.nio.file.Paths;

// Activate the license
License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Render a diagonal text stamp as the foreground layer
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
    "<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);

// Apply the foreground to all pages
pdf.addForegroundPdf(foreground);

pdf.saveAs(Paths.get("overlayForeground.pdf"));

import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import java.nio.file.Paths;

// Activate the license
License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Render a diagonal text stamp as the foreground layer
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
    "<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);

// Apply the foreground to all pages
pdf.addForegroundPdf(foreground);

pdf.saveAs(Paths.get("overlayForeground.pdf"));

Java

The opacity CSS property controls transparency so the foreground stamp does not fully obscure the underlying content. The transform: rotate() property applies diagonal orientation, which is standard for draft and confidential watermarks. The library handles all compositing internally; no manual PDF stream manipulation is required.

Please note: Foreground rendering uses the same HTML-to-PDF engine as renderHtmlAsPdf. Any CSS that works in a modern browser (including @font-face, flexbox, and CSS variables) will produce identical output in the foreground layer.

What Does the Foreground Output Look Like?

Why Use Foreground Overlays Instead of Backgrounds?

Foreground overlays serve a different role than backgrounds and are the correct choice when the added content must appear on top of existing page material:

Draft and confidential stamps: Place prominent but transparent text across pages without removing existing content.
Approval and review annotations: Overlay sign-off indicators or reviewer notes on completed documents.
Security identifiers: Add tracking codes or unique document identifiers that sit above all page content.
Expiry indicators: Mark time-sensitive documents with visible notices that appear above data tables or charts.
Certification marks: Apply logos or seals over finalized content in a way that cannot be covered by existing page elements.

Foreground overlays work well with PDF form filling in Java when you need to place status indicators or approval stamps over completed form data.

How Do I Add a Foreground to Specific Pages?

The addForegroundPdf method accepts a PageSelection argument in the same way as addBackgroundPdf. Use PageSelection.pageRange(int start, int end) to limit the foreground to a contiguous range, or pass a List<Integer> to target non-sequential pages.

import com.ironsoftware.ironpdf.*;
import com.ironsoftware.ironpdf.edit.PageSelection;
import java.nio.file.Paths;

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Render the foreground overlay
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
    "<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);

// Apply the foreground to pages 2 through 8 (zero-based index: 1 to 7)
pdf.addForegroundPdf(foreground, PageSelection.pageRange(2, 8));

pdf.saveAs(Paths.get("overlayForeground.pdf"));

import com.ironsoftware.ironpdf.*;
import com.ironsoftware.ironpdf.edit.PageSelection;
import java.nio.file.Paths;

// Load the target PDF
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));

// Render the foreground overlay
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
    "<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);

// Apply the foreground to pages 2 through 8 (zero-based index: 1 to 7)
pdf.addForegroundPdf(foreground, PageSelection.pageRange(2, 8));

pdf.saveAs(Paths.get("overlayForeground.pdf"));

Java

Important: The pageRange index is one-based in some overloads and zero-based in others depending on which overload you call. Check the IronPDF Java API Reference for the specific overload signature to confirm the indexing convention in your version.

When Should You Use Page Ranges for Foregrounds?

Page-specific foreground application is useful in several production scenarios:

Document sections: Stamp a "DRAFT" overlay only on the appendix or supplementary pages.
Version tracking: Mark updated pages with a revision stamp while leaving unchanged pages unmodified.
Selective confidentiality: Apply a "RESTRICTED" overlay only to the pages containing sensitive financial or medical data.
Multi-language documents: Place language-specific notices on the relevant pages of a bilingual document.
Contract management: Add a "VOID" overlay to expired contract pages without modifying the full document.

What Are Common Page Selection Patterns?

The following patterns cover most selective overlay scenarios:

import com.ironsoftware.ironpdf.*;
import com.ironsoftware.ironpdf.edit.PageSelection;
import java.util.ArrayList;
import java.util.List;
import java.nio.file.Paths;

PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
PdfDocument foreground = PdfDocument.renderHtmlAsPdf("<h1 style='opacity: 0.4;'>DRAFT</h1>");
PdfDocument background1 = PdfDocument.fromFile(Paths.get("cover-background.pdf"));
PdfDocument background2 = PdfDocument.fromFile(Paths.get("end-background.pdf"));

// Apply foreground to all even-numbered pages (zero-based)
List<Integer> evenPages = new ArrayList<>();
for (int i = 1; i < pdf.getPageCount(); i += 2) {
    evenPages.add(i);
}
pdf.addForegroundPdf(foreground, PageSelection.pageRange(evenPages));

// Apply different backgrounds to the first and last pages
pdf.addBackgroundPdf(background1, 0, PageSelection.firstPage());
pdf.addBackgroundPdf(background2, 0, PageSelection.lastPage());

// Apply foreground to all pages except the first and last
if (pdf.getPageCount() > 2) {
    pdf.addForegroundPdf(foreground, PageSelection.pageRange(1, pdf.getPageCount() - 2));
}

pdf.saveAs(Paths.get("selective-overlay.pdf"));

import com.ironsoftware.ironpdf.*;
import com.ironsoftware.ironpdf.edit.PageSelection;
import java.util.ArrayList;
import java.util.List;
import java.nio.file.Paths;

PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
PdfDocument foreground = PdfDocument.renderHtmlAsPdf("<h1 style='opacity: 0.4;'>DRAFT</h1>");
PdfDocument background1 = PdfDocument.fromFile(Paths.get("cover-background.pdf"));
PdfDocument background2 = PdfDocument.fromFile(Paths.get("end-background.pdf"));

// Apply foreground to all even-numbered pages (zero-based)
List<Integer> evenPages = new ArrayList<>();
for (int i = 1; i < pdf.getPageCount(); i += 2) {
    evenPages.add(i);
}
pdf.addForegroundPdf(foreground, PageSelection.pageRange(evenPages));

// Apply different backgrounds to the first and last pages
pdf.addBackgroundPdf(background1, 0, PageSelection.firstPage());
pdf.addBackgroundPdf(background2, 0, PageSelection.lastPage());

// Apply foreground to all pages except the first and last
if (pdf.getPageCount() > 2) {
    pdf.addForegroundPdf(foreground, PageSelection.pageRange(1, pdf.getPageCount() - 2));
}

pdf.saveAs(Paths.get("selective-overlay.pdf"));

Java

Tips: Chain multiple addBackgroundPdf and addForegroundPdf calls on the same PdfDocument to build layered templates. For example, apply a brand color fill as the background, then add a confidentiality stamp as the foreground in a single pipeline.

What Methods Does the `PageSelection` Class Provide?

The PageSelection class controls which pages receive the background or foreground layer. All built-in factory methods return a PageSelection object accepted by both addBackgroundPdf and addForegroundPdf.

PageSelection factory methods for targeting specific pages in addBackgroundPdf and addForegroundPdf

Method	Description
`firstPage()`	Targets the first page of the PDF
`lastPage()`	Targets the last page of the PDF
`singlePage(int index)`	Targets one page by zero-based index
`pageRange(int start, int end)`	Targets a contiguous page range (inclusive)
`pageRange(List<Integer> pageList)`	Targets a non-sequential list of pages
`allPages()`	Targets all pages (default when no selection is passed)

How Do You Choose the Right `PageSelection` Method?

The choice of method depends on the document structure and the extent of the overlay:

firstPage(): Cover pages, title pages, and introductory design elements.
lastPage(): Signature blocks, end-of-document notices, and closing summaries.
singlePage(): Certificates, forms, or individual pages requiring specific treatment.
pageRange(start, end): Chapters, appendices, or any continuous document section.
pageRange(List): Non-sequential selections such as all odd pages or a manually specified set.

For complete parameter documentation and method overload signatures, see the IronPDF Java API Reference.

What Are the Next Steps for Adding Backgrounds and Foregrounds to PDFs?

The addBackgroundPdf and addForegroundPdf methods cover the full range of PDF overlay scenarios, from simple color fills and watermarks to multi-template document assembly workflows. Combine them with PageSelection to apply different designs per section, or chain them with other PdfDocument methods to build production-ready document pipelines. For additional overlay techniques such as text and image stamps, explore the stamp text and images guide or annotations examples for Java.

To use these features in your project, start a free trial of IronPDF for Java or view licensing options for commercial deployment. IronPDF is available via Maven Central and supports Java 8 and later on Windows, Linux, and macOS.

Ready to see what else IronPDF can do? Explore the complete HTML to PDF tutorial for Java for a full walkthrough of rendering, manipulation, and export options.

Frequently Asked Questions

How can I add a background to a PDF using IronPDF in Java?

To add a background to a PDF using IronPDF, use the `addBackgroundPdf` method on a `PdfDocument` instance. First, render the desired background as a PDF via the `renderHtmlAsPdf` method, then pass this PDF as the background source. Ensure IronPDF is set up with your license key.

What is the benefit of using HTML for creating PDF backgrounds?

Using HTML for PDF backgrounds offers precise CSS control, page-size adaptability, dynamic generation, and lightweight output. This allows for complex designs like gradient fills and repeating patterns without manual PDF manipulation.

How do I apply a foreground overlay to a specific page range in a PDF?

To apply a foreground overlay to specific pages, use the `addForegroundPdf` method with a `PageSelection` parameter. You can specify a page range using `PageSelection.pageRange(int start, int end)` to limit the overlay to your desired pages.

Why use foreground overlays instead of backgrounds?

Foreground overlays are used when content needs to be visible on top of existing page material, such as for draft and confidential stamps, approval annotations, and certification marks. They ensure the added content remains prominent.

How can PageSelection methods be used for custom overlays?

PageSelection methods like `firstPage()`, `lastPage()`, `singlePage(int index)`, and `pageRange(int start, int end)` let you target specific pages for background or foreground overlay. This is useful for applying designs to sections like cover pages or appendices.

What are the steps to add a foreground overlay using IronPDF?

To add a foreground overlay, first render the overlay's HTML to a PDF using `renderHtmlAsPdf`. Then, apply it with `addForegroundPdf` to your target `PdfDocument`. Use `PageSelection` for page-specific overlays if needed.

Can IronPDF handle CSS for designing PDF overlays?

Yes, IronPDF uses an HTML-to-PDF engine that supports modern CSS, including gradients, typography, and images. This capability allows you to use any CSS that works in a browser for your PDF overlays.

How do you choose between backgrounds and foregrounds for PDF overlays?

Choose backgrounds for designs beneath existing content, like watermarks and letterheads, and foregrounds for layers above existing content, like approval stamps and annotations, which should be visible regardless of the underlying material.

How can I use IronPDF to compress PDFs after applying overlays?

After applying high-resolution overlays, you can use IronPDF's PDF compression features to reduce file sizes, which is useful for distribution or archiving. Refer to IronPDF's compression examples for implementation.

What is required to start using IronPDF in a Java project?

To use IronPDF in a Java project, include it as a dependency in your `pom.xml` from Maven Central, and activate your license key before executing API calls. Full setup details are available in IronPDF's documentation.

Curtis Chau

Chat with engineering team now

Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...