How to Set Custom Margins in IronPDF C#
IronPDF enables developers to set custom margins when rendering PDFs from HTML through simple configuration of the ChromePdfRenderer's RenderingOptions, allowing precise control over top, bottom, left, and right margins in millimeters.
Set custom margins when rendering PDFs from HTML with simple configuration.
-
1Install IronPDF with NuGet Package Manager
-
2Copy and run this code snippet.
new IronPdf.ChromePdfRenderer { RenderingOptions = { MarginTop = 10, MarginBottom = 10, MarginLeft = 10, MarginRight = 10, UseMarginsOnHeaderAndFooter = IronPdf.UseMargins.All } } .RenderHtmlAsPdf("<h1>Hello with margins!</h1>") .SaveAs("custom-margins.pdf");C# -
3Deploy to test on your live environment
Start using IronPDF in your project today with a free trial
Minimal Workflow (5 Steps):
- Download IronPDF from NuGet
- Instantiate the
ChromePdfRendererclass - Set margin values in
RenderingOptions - Configure header and footer margin behavior
- Render HTML to PDF and save
How Do I Set Custom PDF Margins in IronPDF?
To set custom margins, instantiate the ChromePdfRenderer class. Access the RenderingOptions object to set specific margins in millimeters for top, bottom, left, and right:
ChromePdfRenderer renderer = new ChromePdfRenderer();
renderer.RenderingOptions.MarginTop = 40;
renderer.RenderingOptions.MarginLeft = 20;
renderer.RenderingOptions.MarginRight = 20;
renderer.RenderingOptions.MarginBottom = 40;Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.MarginTop = 40
renderer.RenderingOptions.MarginLeft = 20
renderer.RenderingOptions.MarginRight = 20
renderer.RenderingOptions.MarginBottom = 40Output
The heading and paragraph sit inside the 40mm top and bottom and 20mm left and right margins set on the renderer.
The margin settings work with IronPDF's Chrome rendering engine, which provides accurate HTML to PDF conversion. For advanced PDF generation settings, see the guide on rendering options.
How Do Margins Interact with CSS Styles?
Margins add to those set in the HTML style section. In the example below, HTML margins are 50mm, and RenderingOptions adds 30mm, resulting in 80mm total margins:
const string htmlWithStyle = @"
<!DOCTYPE html>
<html>
<head>
<style>
body {margin: 50mm 50mm 50mm 50mm;}
</style>
</head>
<body>
<h1>Hello World!</h1>
</body>
</html>";
ChromePdfRenderer renderer = new ChromePdfRenderer();
renderer.RenderingOptions.MarginTop = 30;
renderer.RenderingOptions.MarginLeft = 30;
renderer.RenderingOptions.MarginRight = 30;
renderer.RenderingOptions.MarginBottom = 30;
PdfDocument pdf = renderer.RenderHtmlAsPdf(htmlWithStyle);
pdf.SaveAs("PdfWithCustomMargins.pdf");Const htmlWithStyle As String = "
<!DOCTYPE html>
<html>
<head>
<style>
body {margin: 50mm 50mm 50mm 50mm;}
</style>
</head>
<body>
<h1>Hello World!</h1>
</body>
</html>"
Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.MarginTop = 30
renderer.RenderingOptions.MarginLeft = 30
renderer.RenderingOptions.MarginRight = 30
renderer.RenderingOptions.MarginBottom = 30
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(htmlWithStyle)
pdf.SaveAs("PdfWithCustomMargins.pdf")Output
The 50mm CSS body margins and the 30mm RenderingOptions margins combine, so the content is inset 80mm on every side.
When working with CSS in HTML documents, IronPDF supports responsive CSS and media queries, allowing professional layouts. This margin behavior matters when converting HTML files to PDF or working with HTML strings.
How Do I Control Whether CSS @page or C# Margins Win?
The example above adds CSS body margins to your RenderingOptions margins. CSS @page rules are separate: by default IronPDF leaves their margins untouched. When you need the @page margins and your RenderingOptions margins to follow a defined precedence, set RenderingOptions.CssPageRulePolicy:
CssPageRulePolicy | Behavior |
|---|---|
Default | Legacy behavior; IronPDF does not touch CSS @page margins. This is the default. |
RenderingOptionsWin | The C# RenderingOptions.Margin* values win; margin declarations inside @page are stripped and replaced. |
CssPageWin | The CSS @page margins win; IronPDF reads and applies them so the body and the header/footer band agree. |
using IronPdf;
using IronPdf.Rendering;
const string htmlWithAtPageRule = @"
<!DOCTYPE html>
<html>
<head>
<style>
@page { margin: 25mm 20mm 25mm 20mm; }
</style>
</head>
<body>
<h1>Hello World!</h1>
</body>
</html>";
ChromePdfRenderer renderer = new ChromePdfRenderer();
// Let the HTML's own @page rule dictate margins; C# only sets size/orientation and header/footer
renderer.RenderingOptions.CssPageRulePolicy = CssPageRulePolicy.CssPageWin;
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
PdfDocument pdf = renderer.RenderHtmlAsPdf(htmlWithAtPageRule);
pdf.SaveAs("PdfWithCssPageMargins.pdf");Output
Under CssPageWin the CSS @page rule wins, giving 25mm top and bottom and 20mm left and right margins.
CssPageRulePolicy controls page margins only. It does not set page size or orientation, which always come from RenderingOptions.PaperSize and PaperOrientation. Under CssPageWin, only the sides your CSS actually declares are applied (if @page omits margin-bottom, no footer space is reserved), and header/footer auto-sizing is disabled, so give any header/footer a concrete MaxHeight. If an @page rule uses margin-box at-rules such as @top-center, its margins may not be fully reconciled and a warning is logged.What Are Common Margin Values for Different Standards?
Documents often require specific margins to meet various standards. MLA and APA formats require 1-inch margins, while dissertations may need 1.5-inch margins.
Common margin standards and millimeter equivalents:
- MLA/APA Format: 1 inch (25.4mm) all sides
- Dissertation Format: 1.5 inches (38.1mm) all sides
- Business Letters: 1 inch sides, 2 inches (50.8mm) top/bottom
- European A4 Standard: 20mm all sides
- Narrow Margins: 0.5 inches (12.7mm) all sides
When implementing these standards, IronPDF supports custom paper sizes, allowing documents that meet specific regional or organizational requirements.
How Can I Apply Custom Margins to Headers and Footers?
By default, margins set in RenderingOptions don't apply to headers and footers. To apply document margins to headers and footers, configure the UseMarginsOnHeaderAndFooter property:
renderer.RenderingOptions.UseMarginsOnHeaderAndFooter = UseMargins.All;renderer.RenderingOptions.UseMarginsOnHeaderAndFooter = UseMargins.AllOutput
The header and footer line up with the 25mm document margins instead of spanning the full page width.
For header and footer implementation with dynamic content and styling, see the guide on adding headers and footers.
How Do I Apply Margins Selectively to Headers and Footers?
Specify which margins apply to headers and footers. See the API Reference for detailed configuration. Examples:
// Use only the left margin from the document.
renderer.RenderingOptions.UseMarginsOnHeaderAndFooter = UseMargins.Left;
// Use only the left and right margins from the document.
renderer.RenderingOptions.UseMarginsOnHeaderAndFooter = UseMargins.LeftAndRight;' Use only the left margin from the document.
renderer.RenderingOptions.UseMarginsOnHeaderAndFooter = UseMargins.Left
' Use only the left and right margins from the document.
renderer.RenderingOptions.UseMarginsOnHeaderAndFooter = UseMargins.LeftAndRightOutput
With UseMargins.LeftAndRight, only the left and right document margins are applied to the header and footer.
When Should I Use Different Header/Footer Margin Configurations?
Selective margin configurations for headers and footers work well for documents with asymmetric layouts, such as books with alternating page margins or headers extending to page edges while body content maintains margins.
Common use cases:
- Book Publishing: Alternating inner/outer margins for binding
- Letterhead Documents: Full-width headers with constrained body
- Forms and Templates: Different margins for fields versus instructions
- Multi-column Layouts: Full-width headers with column margins
My favorite library of this kind is IronPDF. It allows for fast and efficient manipulation of PDF files. It also has many valuable features, like exporting to PDF/A format and digitally signing PDF documents.
IronOCR means we can save $40,000 annually from manual processing, while enhancing productivity and freeing up resources for high-impact tasks. I would highly recommend it.
The IronSuite play a crucial role in our operations. These are tools that increase efficiencies across the business including creating floor plans and improving inventory management.
Advanced Margin Considerations
Working with Page Breaks and Margins
Custom margins interact with page breaks. IronPDF handles content flow across pages while respecting margin settings, ensuring consistent formatting in multi-page documents.
Margin Units and Precision
IronPDF uses millimeters for margins. Convert from other units:
- Inches to mm: multiply by 25.4
- Points to mm: multiply by 0.352778
- Pixels to mm: varies by DPI (at 96 DPI, multiply by 0.264583)
IronPDF supports decimal values for sub-millimeter precision when needed.
Performance Optimization with Margins
For large documents with custom margins:
- Set margins once at
rendererlevel - Use consistent values across similar documents
- Combine margin settings with other rendering options
Integration with Other IronPDF Features
Custom margins work with other IronPDF capabilities:
- Watermarks and stamps respect boundaries
- PDF compression maintains integrity
- Digital signatures position relative to margins
Conclusion
Setting custom margins in IronPDF provides precise control over PDF layout and formatting. Whether creating business documents, academic papers, or custom reports, IronPDF's margin system ensures PDFs meet exact specifications. Explore the documentation to discover how IronPDF can streamline your PDF generation workflow.
Frequently Asked Questions
How do I set custom margins in IronPDF?
To set custom margins in IronPDF, instantiate the ChromePdfRenderer class, and set margin values in the RenderingOptions object. This allows you to specify top, bottom, left, and right margins in millimeters.
Can IronPDF apply margin settings from CSS @page rules?
Yes, IronPDF can apply margins from CSS @page rules. By setting RenderingOptions.CssPageRulePolicy, you can define whether C# margins or CSS @page margins should take precedence.
What are the common margin sizes for different document standards in IronPDF?
Common margin sizes include 1 inch (25.4mm) for MLA/APA formats, 1.5 inches (38.1mm) for dissertations, and 20mm for European A4 standards. IronPDF supports configuring these standards using its RenderingOptions.
How do margins interact with HTML CSS styles in IronPDF?
Margins set in IronPDF’s RenderingOptions are added to those defined in an HTML document's CSS. If an HTML body has a 50mm margin and IronPDF adds 30mm, the total margin will be 80mm on all sides.
Can I apply custom margins to headers and footers in IronPDF?
Yes, you can apply custom margins to headers and footers in IronPDF by setting the UseMarginsOnHeaderAndFooter property in the RenderingOptions to UseMargins.All, for example.
What options does IronPDF provide for selective header and footer margins?
IronPDF allows selective application of margins to headers and footers with UseMargins settings like UseMargins.Left or UseMargins.LeftAndRight, tailoring margins to specific document layout needs.
How does IronPDF handle page breaks with custom margins?
IronPDF respects custom margin settings when managing page breaks, ensuring consistent formatting across multi-page documents without disrupting the flow of content.
What units does IronPDF use for margins and how can I convert other units?
IronPDF uses millimeters for margins. To convert other units: multiply inches by 25.4, points by 0.352778, and pixels by 0.264583 at 96 DPI.
How can setting margins at the `renderer` level optimize performance in IronPDF?
Setting margins once at the renderer level helps optimize performance by maintaining consistency across large documents and reducing redundant calculations, especially when combined with other rendering options.
Do custom margins work with other IronPDF features like watermarks?
Yes, custom margins in IronPDF are compatible with other features like watermarks, stamps, PDF compression, and digital signatures, maintaining content integrity relative to margin boundaries.
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.
