Backgrounds & Foregrounds

from ironpdf import *

# Instantiate Renderer
renderer = ChromePdfRenderer()

# Render a PDF from a URL
pdf = renderer.RenderUrlAsPdf("https://www.nuget.org/packages/IronPdf")

# Add a PDF as background
pdf.AddBackgroundPdf("MyBackground.pdf")

# Add a PDF as foreground overlay to the first page
pdf.AddForegroundOverlayPdfToPage(0, "MyForeground.pdf", 0)

# Save the merged PDF
pdf.SaveAs("Complete.pdf")

Backgrounds & Foregrounds

IronPDF for Python can layer PDF documents by adding one PDF as a background behind the content of another, or as a foreground overlay on top of it — useful for applying letterhead, watermarks, or design templates to generated documents.

Getting Started

Load or render a base PdfDocument, then call AddBackgroundPdf or AddForegroundOverlayPdfToPage to apply another PDF file as a layer. Save the result with SaveAs.

Understanding the Code

AddBackgroundPdf(path): Applies the specified PDF file as a background on every page of the current document. The background appears behind the existing page content.
AddForegroundOverlayPdfToPage(targetPageIndex, path, sourcePageIndex): Overlays a single page from the specified PDF onto a specific page of the current document. The overlay appears on top of the existing content.
- targetPageIndex: The zero-based page index in the current document where the overlay should be applied.
- sourcePageIndex: The zero-based page index within the overlay PDF to use as the source.
SaveAs("Complete.pdf"): Saves the layered document to disk.

Use Cases

Letterhead: Apply a company letterhead PDF as a background to every page of a generated report.
Stamp templates: Overlay a signature block or approval stamp onto a specific page.
Design layers: Separate content from design by maintaining a layout template PDF and combining it with dynamically generated content.