IronPDF How-Tos Backgrounds & Foregrounds How to Add Background and Overlay Foreground on PDFs ByChaknith Bin October 9, 2023 Updated June 22, 2025 Share: Adding a background allows you to insert an image or another PDF document as a background layer behind the existing content of a PDF. It's useful for creating letterheads, watermarks, or adding decorative elements to your documents.Overlaying the foreground lets you place text, images, or other content on top of an existing PDF, effectively overlaying it. This is commonly used for adding annotations, stamps, signatures, or additional information to a PDF without altering the original content.Adding a background and overlaying the foreground are both available in IronPdf with the options to use PDF as background and foreground. View the IronPDF YouTube Playlist Get started with IronPDF Start using IronPDF in your project today with a free trial. First Step: Start for Free How to Add Background and Overlay Foreground on PDFs Download the IronPDF Library from NuGet Use a freshly rendered or existing PDF as a background or foreground Use the AddBackgroundPdf method to add a background Use the AddForegroundOverlayPdf method to overlay a foreground Specify which pages to apply the background or foreground Add Background Example Utilize the AddBackgroundPdf method to add a background to a newly rendered or existing PDF document. The code example below demonstrates providing the method with a PdfDocument object. However, you can also specify the file path to automatically import the PDF and add it as the background in a single line of code. Code :path=/static-assets/pdf/content-code-examples/how-to/background-foreground-background.cs using IronPdf; // This example demonstrates how to render an HTML document to a PDF with a background using IronPdf. // Create a renderer for PDF generation using ChromePdfRenderer ChromePdfRenderer renderer = new ChromePdfRenderer(); // Render the main HTML content to a PDF document // This main content will be layered on top of any background content we add later. PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>"); // Render a separate PDF document that will serve as the background. // We are using a simple cyan background color for demonstration purposes. PdfDocument background = renderer.RenderHtmlAsPdf("<body style='background-color: cyan;'></body>"); // Add the background PDF as the background for the main PDF document. // This method allows for overlaying the original document content on top of the background. pdf.AddBackgroundPdf(background); // Save the final PDF document with the background to a file named "addBackground.pdf". // The resultant PDF will have the main content overlayed on top of the cyan background. pdf.SaveAs("addBackground.pdf"); Imports IronPdf ' This example demonstrates how to render an HTML document to a PDF with a background using IronPdf. ' Create a renderer for PDF generation using ChromePdfRenderer Private renderer As New ChromePdfRenderer() ' Render the main HTML content to a PDF document ' This main content will be layered on top of any background content we add later. Private pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>") ' Render a separate PDF document that will serve as the background. ' We are using a simple cyan background color for demonstration purposes. Private background As PdfDocument = renderer.RenderHtmlAsPdf("<body style='background-color: cyan;'></body>") ' Add the background PDF as the background for the main PDF document. ' This method allows for overlaying the original document content on top of the background. pdf.AddBackgroundPdf(background) ' Save the final PDF document with the background to a file named "addBackground.pdf". ' The resultant PDF will have the main content overlayed on top of the cyan background. pdf.SaveAs("addBackground.pdf") $vbLabelText $csharpLabel Output PDF Overlay Foreground Example Similar to adding a background, you can specify the PDF file path to import the document and overlay it as a foreground over the main PDF. Use the AddForegroundOverlayPdf method to overlay the foreground on the main PDF document. Code :path=/static-assets/pdf/content-code-examples/how-to/background-foreground-foreground.cs // Import the IronPdf library which provides functionalities for generating PDFs. using IronPdf; // Create an instance of the ChromePdfRenderer, which allows rendering PDFs from HTML content. ChromePdfRenderer renderer = new ChromePdfRenderer(); // Render the main PDF document from an HTML string. // This creates a PDF with the specified HTML content ("<h1>Main HTML content</h1>"). PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>"); // Render the overlay foreground PDF from another HTML string. // This creates a watermark with rotation and transparency effects. PdfDocument foreground = renderer.RenderHtmlAsPdf("<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Overlay Watermark</h1>"); // Overlay the watermark PDF onto the main PDF as a foreground. // This means the watermark will sit on top of the content of the main PDF. pdf.AddForegroundOverlayPdf(foreground); // Save the final PDF with the overlay applied to a file named "overlayForeground.pdf". pdf.SaveAs("overlayForeground.pdf"); ' Import the IronPdf library which provides functionalities for generating PDFs. Imports IronPdf ' Create an instance of the ChromePdfRenderer, which allows rendering PDFs from HTML content. Private renderer As New ChromePdfRenderer() ' Render the main PDF document from an HTML string. ' This creates a PDF with the specified HTML content ("<h1>Main HTML content</h1>"). Private pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>") ' Render the overlay foreground PDF from another HTML string. ' This creates a watermark with rotation and transparency effects. Private foreground As PdfDocument = renderer.RenderHtmlAsPdf("<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Overlay Watermark</h1>") ' Overlay the watermark PDF onto the main PDF as a foreground. ' This means the watermark will sit on top of the content of the main PDF. pdf.AddForegroundOverlayPdf(foreground) ' Save the final PDF with the overlay applied to a file named "overlayForeground.pdf". pdf.SaveAs("overlayForeground.pdf") $vbLabelText $csharpLabel Output PDF Select Pages for Background or Foreground It is possible to choose which page of the PDF to use as your background or foreground. Let's take applying a background as an example, using a similar code example from the 'Add Background Example' section. We generate a two-page PDF with a different color to use as the background. By specifying the number 1 as our second parameter in the AddBackgroundPdf method, we use the 2nd page as the background. TipsAll page indexes follow zero-based indexing. Code :path=/static-assets/pdf/content-code-examples/how-to/background-foreground-background-page-2.cs using IronPdf; // Define HTML content for the background pages. // The backgroundHtml string represents different page styles using div elements. // 'page-break-after: always;' ensures that each div is rendered on its own page. string backgroundHtml = @" <div style='background-color: cyan; height: 100%; width:100%;'></div> <div style='page-break-after: always;'></div> <div style='background-color: lemonchiffon; height: 100%; width:100%;'></div>"; // Create a new instance of ChromePdfRenderer, which will render HTML content as PDF. ChromePdfRenderer renderer = new ChromePdfRenderer(); // Render the primary HTML content as a PDF document. This example creates a simple single-page PDF. PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>"); // Render the background HTML content into another PDF document. // Each <div> will correspond to a separate page in the rendered PDF. PdfDocument background = renderer.RenderHtmlAsPdf(backgroundHtml); // Apply the background from the second page (index 1) of the background PDF // to all pages of the main content PDF. pdf.AddBackgroundPdf(background, 1); // Save the combined PDF document to a file named "addBackgroundFromPage2.pdf". pdf.SaveAs("addBackgroundFromPage2.pdf"); // Important Notes: // - Ensure that IronPdf library references are properly added to the project. // - The div elements with full height and width ensure full page backgrounds. // - The 'AddBackgroundPdf' function uses zero-based indexing. Imports IronPdf ' Define HTML content for the background pages. ' The backgroundHtml string represents different page styles using div elements. ' 'page-break-after: always;' ensures that each div is rendered on its own page. Private backgroundHtml As String = " <div style='background-color: cyan; height: 100%; width:100%;'></div> <div style='page-break-after: always;'></div> <div style='background-color: lemonchiffon; height: 100%; width:100%;'></div>" ' Create a new instance of ChromePdfRenderer, which will render HTML content as PDF. Private renderer As New ChromePdfRenderer() ' Render the primary HTML content as a PDF document. This example creates a simple single-page PDF. Private pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>") ' Render the background HTML content into another PDF document. ' Each <div> will correspond to a separate page in the rendered PDF. Private background As PdfDocument = renderer.RenderHtmlAsPdf(backgroundHtml) ' Apply the background from the second page (index 1) of the background PDF ' to all pages of the main content PDF. pdf.AddBackgroundPdf(background, 1) ' Save the combined PDF document to a file named "addBackgroundFromPage2.pdf". pdf.SaveAs("addBackgroundFromPage2.pdf") ' Important Notes: ' - Ensure that IronPdf library references are properly added to the project. ' - The div elements with full height and width ensure full page backgrounds. ' - The 'AddBackgroundPdf' function uses zero-based indexing. $vbLabelText $csharpLabel Output PDF Apply Background or Foreground on Specified Pages Lastly, it is also possible to apply background or foreground to a single page or multiple pages. This action requires using a slightly different method name. Use the AddBackgroundPdfToPage and AddForegroundOverlayPdfToPage methods for adding background and overlaying foreground to a single particular page of the PDF, respectively. TipsAll page indexes follow zero-based indexing. Apply on a Single Page :path=/static-assets/pdf/content-code-examples/how-to/background-foreground-single-page.cs using IronPdf; // Initialize a new instance of ChromePdfRenderer, which will be used to render HTML to PDF. ChromePdfRenderer renderer = new ChromePdfRenderer(); // Render the main HTML content as a PDF document. PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>"); // Render the background as a separate PDF document. // Here we are rendering an HTML page with a cyan background color. PdfDocument background = renderer.RenderHtmlAsPdf("<body style='background-color: cyan; height:100vh; margin:0;'></body>"); // Add the rendered background to the first page of the main PDF document. // Since the pages are zero-indexed, '0' refers to the first page. pdf.Pages[0].AddBackground(background.Pages[0]); // Save the final PDF document, which includes the background, to a file. pdf.SaveAs("addBackgroundOnASinglePage.pdf"); Imports IronPdf ' Initialize a new instance of ChromePdfRenderer, which will be used to render HTML to PDF. Private renderer As New ChromePdfRenderer() ' Render the main HTML content as a PDF document. Private pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Main HTML content</h1>") ' Render the background as a separate PDF document. ' Here we are rendering an HTML page with a cyan background color. Private background As PdfDocument = renderer.RenderHtmlAsPdf("<body style='background-color: cyan; height:100vh; margin:0;'></body>") ' Add the rendered background to the first page of the main PDF document. ' Since the pages are zero-indexed, '0' refers to the first page. pdf.Pages(0).AddBackground(background.Pages(0)) ' Save the final PDF document, which includes the background, to a file. pdf.SaveAs("addBackgroundOnASinglePage.pdf") $vbLabelText $csharpLabel Apply on Multiple Pages :path=/static-assets/pdf/content-code-examples/how-to/background-foreground-multiple-pages.cs // Import the necessary namespaces for PDF generation and collections using IronPdf; using System.Collections.Generic; // HTML content with manual page breaks string html = @" <p>This is 1st Page</p> <div style='page-break-after: always;'></div> <p>This is 2nd Page</p> <div style='page-break-after: always;'></div> <p>This is 3rd Page</p>"; // Initialize the PDF renderer ChromePdfRenderer renderer = new ChromePdfRenderer(); // Render the HTML content as a PDF document PdfDocument pdf = renderer.RenderHtmlAsPdf(html); // Create a background PDF with a specified background color PdfDocument background = renderer.RenderHtmlAsPdf("<body style='background-color: cyan;'></body>"); // Create a list of page indices to which the background will be added. // In IronPdf, pages are indexed from 0. List<int> pages = new List<int>() { 0, 2 }; // Apply the background PDF to the specified pages pdf.AddBackgroundPdfToPageRange(pages, background); // Save the finalized PDF document to a file pdf.SaveAs("addBackgroundOnMultiplePage.pdf"); ' Import the necessary namespaces for PDF generation and collections Imports IronPdf Imports System.Collections.Generic ' HTML content with manual page breaks Private html As String = " <p>This is 1st Page</p> <div style='page-break-after: always;'></div> <p>This is 2nd Page</p> <div style='page-break-after: always;'></div> <p>This is 3rd Page</p>" ' Initialize the PDF renderer Private renderer As New ChromePdfRenderer() ' Render the HTML content as a PDF document Private pdf As PdfDocument = renderer.RenderHtmlAsPdf(html) ' Create a background PDF with a specified background color Private background As PdfDocument = renderer.RenderHtmlAsPdf("<body style='background-color: cyan;'></body>") ' Create a list of page indices to which the background will be added. ' In IronPdf, pages are indexed from 0. Private pages As New List(Of Integer)() From {0, 2} ' Apply the background PDF to the specified pages pdf.AddBackgroundPdfToPageRange(pages, background) ' Save the finalized PDF document to a file pdf.SaveAs("addBackgroundOnMultiplePage.pdf") $vbLabelText $csharpLabel Output PDF Frequently Asked Questions What is the purpose of adding a background to a PDF? Adding a background allows you to insert an image or another PDF document as a background layer behind the existing content of a PDF. It's useful for creating letterheads, watermarks, or adding decorative elements to your documents using IronPDF. How can I overlay content on top of an existing PDF? Overlaying the foreground lets you place text, images, or other content on top of an existing PDF, effectively overlaying it. This is commonly used for adding annotations, stamps, signatures, or additional information to a PDF without altering the original content using IronPDF. Which methods are used for adding backgrounds and foreground overlays? In IronPDF, you can use the AddBackgroundPdf method to add a background and the AddForegroundOverlayPdf method to overlay a foreground. How do I specify which pages to apply the background or foreground in a PDF? You can specify which pages to apply the background or foreground using the AddBackgroundPdfToPage or AddForegroundOverlayPdfToPage methods for single pages, or use page range methods for multiple pages in IronPDF. Can I use an existing PDF as a background or foreground? Yes, you can use a freshly rendered or existing PDF as a background or foreground by specifying its file path and using the appropriate method in IronPDF. How do I add a background to a PDF? To add a background to a PDF using IronPDF, use the AddBackgroundPdf method with a base PDF and a background PDF. You can specify the page index of the background PDF to be used. How do I overlay a foreground on a PDF? To overlay a foreground on a PDF using IronPDF, use the AddForegroundOverlayPdf method with a base PDF and a foreground PDF. Specify the page index of the foreground PDF to be overlaid. How can I apply a background or foreground to a specific range of pages? To apply a background or foreground to a specific range of pages, use the AddBackgroundPdfToPageRange or AddForegroundOverlayPdfToPageRange methods in IronPDF, specifying the start and end page indexes. Chaknith Bin Chat with engineering team now Software Engineer Chaknith is the Sherlock Holmes of developers. It first occurred to him he might have a future in software engineering, when he was doing code challenges for fun. His focus is on IronXL and IronBarcode, but he takes pride in helping customers with every product. Chaknith leverages his knowledge from talking directly with customers, to help further improve the products themselves. His anecdotal feedback goes beyond Jira tickets and supports product development, documentation and marketing, to improve customer’s overall experience.When he isn’t in the office, he can be found learning about machine learning, coding and hiking. Ready to Get Started? Free NuGet Download Total downloads: 14,143,061 View Licenses