Backgrounds & Foregrounds

For adding specific background or foreground elements to your PDF documents, IronPDF provides the addBackground and addForeground methods. These methods enable developers can use the content of one PDF as the background or the foreground of another PDF. These methods are particularly useful for generating groups of PDFs based on a common design template.

addBackground(PdfDocument backgroundPdf);
addForeground(PdfDocument foregroundPdf);

Since these methods work with PdfDocument objects, developers can source them from existing files using the fromFile method, or generate them anew using one of the available PDF rendering methods.

addBackground and addForeground will use the first page of multipage PDF documents as the background or foreground by default. To use a different page from PDFs containing multiple pages, add the index of the desired page as the second argument to the method call.

// Use the third page of the background PDF as the background of every page  
// in the working PDF  
pdf.addBackground(backgroundPdf, 2);  

// Use the second page of the foreground PDF as the foreground of every page  
// of the working PDF  
pdf.addForeground(foregroundPdf, 1);

For overlaying a PDF as the background or foreground on specific pages of a working PDF, specify the pages to be overlayed using a PageSelection object. The example below shows how to do this for a single page and for a range of pages of a PDF document.

// Add the background to page 5 of the working PDF  
pdf.addBackground(backgroundPdf, PageSelection.singlePage(6));  

// Add a different background on pages 7 through 16 of the working PDF  
pdf.addBackground(backgroundPdf, PageSelection.pageRange(6, 15));  

// Add another background to just the first page.  
pdf.addBackground(backgroundPdf, PageSelection.firstPage());

For watermarking your PDF documents, use the addWatermark method as an alternative to using addBackground for easier control over background positioning and opacity.