DEV Community

IronSoftware
IronSoftware

Posted on

PDF Headers and Footers in C# (.NET Guide)

#csharp #dotnet

Headers and footers appear on every page of your PDF. Add page numbers, document titles, dates, or company logos—IronPDF supports both simple text and full HTML styling.

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.TextHeader = new TextHeaderFooter
{
    CenterText = "Company Report",
    FontSize = 14
};

renderer.RenderingOptions.TextFooter = new TextHeaderFooter
{
    CenterText = "Page {page} of {total-pages}"
};

var pdf = renderer.RenderHtmlAsPdf("<h1>Report Content</h1>");
pdf.SaveAs("report.pdf");
Enter fullscreen mode Exit fullscreen mode

The {page} and {total-pages} placeholders automatically insert page numbers.

What's the Difference Between Text and HTML Headers?

IronPDF offers two approaches:

Type Speed Customization
Text Faster Basic fonts and alignment
HTML Slower Full CSS, images, layouts

Use text headers for simple page numbers. Use HTML headers for branded documents with logos and complex layouts.

How Do I Add Text Headers?

Simple text with positioning:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.TextHeader = new TextHeaderFooter
{
    LeftText = "{date}",
    CenterText = "Confidential",
    RightText = "Page {page}",
    FontSize = 12,
    FontFamily = "Arial"
};

var pdf = renderer.RenderHtmlAsPdf(html);
Enter fullscreen mode Exit fullscreen mode

Three positions: left, center, and right. Each can contain text and placeholders.

What Placeholders Are Available?

Built-in dynamic values:

Placeholder Output
{page} Current page number
{total-pages} Total page count
{date} Current date
{time} Current time
{title} Document title
{url} Source URL (if rendered from URL)

Example:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.TextFooter = new TextHeaderFooter
{
    LeftText = "Generated: {date} {time}",
    RightText = "Page {page} of {total-pages}",
    FontSize = 10
};
Enter fullscreen mode Exit fullscreen mode

How Do I Add HTML Headers?

Full HTML and CSS support:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='display: flex; justify-content: space-between; width: 100%; font-family: Arial;'>
            <img src='logo.png' style='height: 30px;' />
            <span style='color: #666;'>Monthly Report - Q4 2024</span>
        </div>",
    DrawDividerLine = true
};

var pdf = renderer.RenderHtmlAsPdf(content);
Enter fullscreen mode Exit fullscreen mode

HTML headers render with full CSS support—flexbox, images, and custom fonts work.

How Do I Add HTML Footers with Page Numbers?

Use placeholders in HTML:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align: center; font-size: 12px; color: #333;'>
            <span>© 2024 Your Company</span>
            <span style='margin: 0 20px;'>|</span>
            <span>Page {page} of {total-pages}</span>
        </div>",
    DrawDividerLine = true
};
Enter fullscreen mode Exit fullscreen mode

Placeholders work in HTML fragments too.

How Do I Set Header/Footer Height?

Control the space reserved:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

// Header with logo needs more space
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = "<img src='banner.png' style='width:100%;' />",
    MaxHeight = 50 // millimeters
};

// Simple footer needs less space
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    HtmlFragment = "<p style='text-align:center;'>Page {page}</p>",
    MaxHeight = 20
};
Enter fullscreen mode Exit fullscreen mode

How Do I Add a Divider Line?

Separate headers/footers from content:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = "<h2>Document Title</h2>",
    DrawDividerLine = true,
    DividerLineColor = "#cccccc"
};
Enter fullscreen mode Exit fullscreen mode

Or use CSS borders in the HTML itself for more control.

How Do I Add Headers to Existing PDFs?

Add headers/footers after the fact:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var pdf = new PdfDocument("existing-document.pdf");

// Add text headers
pdf.AddTextHeaders(new TextHeaderFooter
{
    CenterText = "CONFIDENTIAL",
    FontSize = 14,
    FontFamily = "Arial"
});

// Add text footers
pdf.AddTextFooters(new TextHeaderFooter
{
    CenterText = "Page {page} of {total-pages}"
});

pdf.SaveAs("document-with-headers.pdf");
Enter fullscreen mode Exit fullscreen mode

Works on any existing PDF.

How Do I Add Headers to Specific Pages?

Target page ranges:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var pdf = new PdfDocument("multipage.pdf");

// Cover page - no header
// Pages 2-10 - content header
// Last page - different footer

// Add header to pages 2-10 (indices 1-9)
pdf.AddTextHeaders(
    new TextHeaderFooter { CenterText = "Chapter Content" },
    pageIndices: Enumerable.Range(1, 9).ToArray()
);

// Different footer for appendix pages
pdf.AddTextFooters(
    new TextHeaderFooter { CenterText = "Appendix - Page {page}" },
    pageIndices: new[] { 10, 11, 12 }
);

pdf.SaveAs("selective-headers.pdf");
Enter fullscreen mode Exit fullscreen mode

How Do I Create Different Odd/Even Headers?

Professional book-style layouts:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var pdf = new PdfDocument("book.pdf");
var pageCount = pdf.PageCount;

// Odd pages: title on right
var oddPages = Enumerable.Range(0, pageCount).Where(i => i % 2 == 0).ToArray();
pdf.AddTextHeaders(
    new TextHeaderFooter { RightText = "Book Title" },
    pageIndices: oddPages
);

// Even pages: chapter on left
var evenPages = Enumerable.Range(0, pageCount).Where(i => i % 2 == 1).ToArray();
pdf.AddTextHeaders(
    new TextHeaderFooter { LeftText = "Chapter 1" },
    pageIndices: evenPages
);

pdf.SaveAs("book-styled.pdf");
Enter fullscreen mode Exit fullscreen mode

How Do I Include Images in Headers?

Embed logos and graphics:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

// Using Base64 for reliable embedding
var logoBytes = File.ReadAllBytes("logo.png");
var base64 = Convert.ToBase64String(logoBytes);

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = $@"
        <div style='display: flex; align-items: center; gap: 10px;'>
            <img src='data:image/png;base64,{base64}' style='height: 30px;' />
            <span style='font-size: 18px; font-weight: bold;'>Company Name</span>
        </div>",
    MaxHeight = 40
};
Enter fullscreen mode Exit fullscreen mode

Base64 ensures images display correctly regardless of file paths.

How Do I Style Headers with CSS?

Full CSS support in HTML headers:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <style>
            .header {
                font-family: 'Georgia', serif;
                display: flex;
                justify-content: space-between;
                padding: 0 20px;
            }
            .title {
                font-size: 16px;
                color: #2c3e50;
            }
            .date {
                font-size: 12px;
                color: #7f8c8d;
            }
        </style>
        <div class='header'>
            <span class='title'>Annual Report 2024</span>
            <span class='date'>{date}</span>
        </div>"
};
Enter fullscreen mode Exit fullscreen mode

Quick Reference

Property Text Header HTML Header
Left text LeftText Use CSS
Center text CenterText Use CSS
Right text RightText Use CSS
Font FontFamily, FontSize CSS fonts
Images Not supported Full support
Divider DrawDividerLine DrawDividerLine or CSS
Method Description
AddTextHeaders() Add to existing PDF
AddTextFooters() Add to existing PDF
AddHtmlHeaders() HTML header to existing PDF
AddHtmlFooters() HTML footer to existing PDF

Headers and footers transform raw content into professional documents ready for printing or distribution.

For more header/footer options, see the IronPDF headers and footers documentation.

Written by Jacob Mellor, CTO at Iron Software. Jacob created IronPDF and leads a team of 50+ engineers building .NET document processing libraries.

Top comments (0)