1. IronPDF
  2. How-Tos
  3. Page Breaks
How to Handle HTML to PDF Page Breaks Using C#

Add or Avoid Page Breaks in HTML PDFs with C#

Curtis Chau
Curtis Chau
Updated:

Control page breaks in PDF documents by adding page-break-after: always; to HTML elements or preventing breaks with page-break-inside: avoid; when converting HTML to PDF using IronPDF in C#.

IronPDF supports page breaks within PDF documents. One major difference between PDF documents and HTML is that HTML documents tend to scroll whereas PDFs are multi-paged and can be printed. When converting HTML strings to PDF, developers often need precise control over where pages break to ensure professional-looking documents.

Quickstart: Implementing Page Breaks in HTML to PDF Conversion

Convert HTML to PDF with page breaks using IronPDF. This example demonstrates inserting a page break after specific HTML content to ensure proper pagination. By adding the page-break-after: always; style, developers control where page breaks occur, improving readability and organization of the resulting PDF document.

Nuget IconGet started making PDFs with NuGet now:

  1. Install IronPDF with NuGet Package Manager

    PM > Install-Package IronPdf

  2. Copy and run this code snippet.

    new IronPdf.ChromePdfRenderer()
  .RenderHtmlAsPdf("<html><body><h1>Hello World!</h1><div style='page-break-after: always;'></div></body></html>")
  .SaveAs("pageWithBreaks.pdf");

  3. Deploy to test on your live environment

    Start using IronPDF in your project today with a free trial
    arrow pointer

Minimal Workflow (5 steps)

IronPDF promotional guide showing 4 steps for HTML PDF page breaks with NuGet install command
  1. Download C# library to use page breaks in PDF
  2. Apply Page Breaks to HTML string and convert it to PDF
  3. Set avoid on page-break-inside attribute to avoid Page Breaks in Images
  4. Do the same for tables to avoid Page Breaks in Tables
  5. Set style at the CSS Level


How Do I Add a Page Break in HTML to PDF?

To create a page break in HTML, use this in your HTML code:

<div style="page-break-after: always;"></div>
<div style="page-break-after: always;"></div>
HTML

The page-break-after CSS property is the most reliable method for controlling pagination when rendering HTML to PDF. This property tells the PDF renderer to insert a page break immediately after the element containing this style. When working with custom margins or specific page layouts, page breaks ensure content appears exactly where intended.

Why Does page-break-after Work Better Than Other Methods?

In this example, I have the following table and image in my HTML, and I want them on two separate pages by adding a page break after the table. The page-break-after property provides more consistent results across different rendering engines compared to alternatives like page-break-before or manual spacing. When creating new PDFs with complex layouts, this approach ensures predictable pagination.

What Elements Should I Use for Page Breaks?

Page breaks work effectively with block-level elements like <div>, <section>, and <article>. While you can apply page break styles to various HTML elements, wrapping content in a dedicated <div> provides the most reliable results. This is particularly important when working with headers and footers that need to appear consistently across pages.

Table

<table style="border: 1px solid #000000">
  <tr>
    <th>Company</th>
    <th>Product</th>
  </tr>
  <tr>
    <td>Iron Software</td>
    <td>IronPDF</td>
  </tr>
  <tr>
    <td>Iron Software</td>
    <td>IronOCR</td>
  </tr>
</table>
<table style="border: 1px solid #000000">
  <tr>
    <th>Company</th>
    <th>Product</th>
  </tr>
  <tr>
    <td>Iron Software</td>
    <td>IronPDF</td>
  </tr>
  <tr>
    <td>Iron Software</td>
    <td>IronOCR</td>
  </tr>
</table>
HTML

Image

<img src="/static-assets/pdf/how-to/html-to-pdf-page-breaks/ironpdf-logo-text-dotnet.svg" style="border:5px solid #000000; padding:3px; margin:5px" />
<img src="/static-assets/pdf/how-to/html-to-pdf-page-breaks/ironpdf-logo-text-dotnet.svg" style="border:5px solid #000000; padding:3px; margin:5px" />
HTML

How Do I Implement Page Breaks in C# Code?

:path=/static-assets/pdf/content-code-examples/how-to/html-to-pdf-page-breaks-page-break.cs
using IronPdf;

const string html = @"
  <table style='border: 1px solid #000000'>
    <tr>
      <th>Company</th>
      <th>Product</th>
    </tr>
    <tr>
      <td>Iron Software</td>
      <td>IronPDF</td>
    </tr>
    <tr>
      <td>Iron Software</td>
      <td>IronOCR</td>
    </tr>
  </table>

  <div style='page-break-after: always;'> </div>

  <img src='https://ironpdf.com/img/products/ironpdf-logo-text-dotnet.svg'>";

var renderer = new ChromePdfRenderer();

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("Page_Break.pdf");
$vbLabelText   $csharpLabel

The code above generates a PDF with 2 pages: the table on the first page and the image on the second:

How Do I Prevent Page Breaks in Images?

To avoid a page break within an image or table, use the CSS page-break-inside attribute applied to a wrapping DIV element. This technique is essential for maintaining visual integrity when debugging HTML with Chrome to ensure your PDFs render exactly as intended.

<div style="page-break-inside: avoid">
    <img src="no-break-me.png" />
</div>
<div style="page-break-inside: avoid">
    <img src="no-break-me.png" />
</div>
HTML

Why Should I Wrap Images in DIV Elements?

Wrapping images in DIV elements provides better control over page break behavior. The page-break-inside: avoid property works most reliably on block-level elements. Images are inline elements by default, so wrapping them ensures the style is properly applied. This approach is particularly useful when working with responsive CSS layouts that need to maintain their structure in PDF format.

What Are Common Issues With Image Page Breaks?

Common issues include images being split across pages, partial rendering at page boundaries, and loss of captions or associated text. These problems often occur when images are near the bottom of a page. Using the page-break-inside: avoid wrapper prevents these issues by ensuring the entire image and its container move to the next page as a unit.

using IronPdf;

// Example showing how to prevent image breaks in a more complex layout
const string htmlWithProtectedImage = @"
<html>
<head>
    <style>
        .no-break { page-break-inside: avoid; }
        .image-container { 
            border: 2px solid #333; 
            padding: 10px; 
            margin: 20px 0;
        }
    </style>
</head>
<body>
    <h1>Product Gallery</h1>
    <p>Our featured products are displayed below:</p>

    <div class='no-break image-container'>
        <img src='product1.jpg' alt='Product 1' />
        <p>Product 1 Description</p>
    </div>

    <div class='no-break image-container'>
        <img src='product2.jpg' alt='Product 2' />
        <p>Product 2 Description</p>
    </div>
</body>
</html>";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlWithProtectedImage);
pdf.SaveAs("ProductGallery.pdf");
using IronPdf;

// Example showing how to prevent image breaks in a more complex layout
const string htmlWithProtectedImage = @"
<html>
<head>
    <style>
        .no-break { page-break-inside: avoid; }
        .image-container { 
            border: 2px solid #333; 
            padding: 10px; 
            margin: 20px 0;
        }
    </style>
</head>
<body>
    <h1>Product Gallery</h1>
    <p>Our featured products are displayed below:</p>

    <div class='no-break image-container'>
        <img src='product1.jpg' alt='Product 1' />
        <p>Product 1 Description</p>
    </div>

    <div class='no-break image-container'>
        <img src='product2.jpg' alt='Product 2' />
        <p>Product 2 Description</p>
    </div>
</body>
</html>";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlWithProtectedImage);
pdf.SaveAs("ProductGallery.pdf");
$vbLabelText   $csharpLabel

How Can I Avoid Page Breaks in Tables?

As shown above, page breaks within tables can be avoided using the CSS page-break-inside: avoid. This is better applied to a wrapping DIV than to the table itself to ensure the style is applied to a block-level HTML node. When creating comprehensive HTML to PDF tutorials, proper table formatting is crucial for readability.

When Should I Use thead for Table Headers?

To duplicate table headers and footers across every page of a large HTML table spanning multiple PDF pages, use a <thead> group within the table:

<thead>
    <tr>
        <th>C Sharp</th><th>VB</th>
    </tr>
</thead>
<thead>
    <tr>
        <th>C Sharp</th><th>VB</th>
    </tr>
</thead>
HTML

The <thead> element ensures that table headers repeat on each page when a table spans multiple pages. This is particularly useful for financial reports, data listings, and any document where context is needed on every page. For initial setup and installation overview, IronPDF handles these HTML standards automatically.

Why Does Wrapping Tables in DIVs Matter?

Wrapping tables in DIV elements with page break controls provides several benefits:

  • Ensures the entire table moves as a unit to the next page if needed
  • Prevents headers from being separated from data rows
  • Allows for additional styling and spacing control
  • Makes it easier to add captions or descriptions that stay with the table

What Advanced CSS3 Settings Control Page Breaks?

To give greater control, use CSS3 in addition to your thead group:

<style type="text/css">
    table { page-break-inside:auto }
    tr { page-break-inside:avoid; page-break-after:auto }
    thead { display:table-header-group }
    tfoot { display:table-footer-group }
</style>
<style type="text/css">
    table { page-break-inside:auto }
    tr { page-break-inside:avoid; page-break-after:auto }
    thead { display:table-header-group }
    tfoot { display:table-footer-group }
</style>
HTML

Which CSS Properties Work Best for Complex Layouts?

For complex layouts, combine multiple CSS properties:

  • page-break-inside: avoid - Prevents elements from splitting
  • page-break-after: always - Forces a break after an element
  • page-break-before: always - Forces a break before an element
  • orphans and widows - Controls minimum lines at page breaks
  • break-inside, break-after, break-before - Modern CSS3 alternatives

These properties work together to create professional-looking PDFs with proper flow and readability.

How Do I Troubleshoot Page Break Issues?

When page breaks don't work as expected:

  1. Verify your HTML structure is valid
  2. Check that styles are applied to block-level elements
  3. Test with simple examples first, then add complexity
  4. Use browser developer tools to inspect computed styles
  5. Consider using IronPDF's rendering options for additional control

Remember that different PDF renderers may handle page breaks slightly differently, so testing with your specific use case is important for achieving consistent results across all scenarios.

Frequently Asked Questions

How do I add a page break when converting HTML to PDF in C#?

To add a page break when using IronPDF, insert `

` in your HTML code where you want the break to occur. IronPDF's ChromePdfRenderer will recognize this CSS property and create a new page at that point in the PDF document.

What CSS property is most reliable for controlling page breaks in PDF conversion?

The `page-break-after: always;` CSS property is the most reliable method when using IronPDF. This property provides consistent results across different rendering engines and ensures predictable pagination in your converted PDF documents.

How can I prevent page breaks inside tables or images?

To prevent unwanted page breaks within tables or images, use the `page-break-inside: avoid;` CSS property. When converting HTML to PDF with IronPDF, this style ensures that your tables and images remain intact on a single page rather than being split across multiple pages.

Which HTML elements work best with page break styles?

Page breaks work most effectively with block-level elements like `

`, ``, and `
`. IronPDF recommends wrapping content in a dedicated `
` element with the page break style for the most reliable results when converting HTML to PDF.

Can I control page breaks at the CSS level instead of inline styles?

Yes, you can set page break styles at the CSS level rather than using inline styles. IronPDF's rendering engine fully supports CSS stylesheets, allowing you to define page break rules in your CSS file and maintain cleaner, more maintainable HTML code.

Why should I use page-break-after instead of page-break-before?

The `page-break-after` property provides more consistent results across different rendering engines compared to `page-break-before`. When using IronPDF to create PDFs with complex layouts, page-break-after ensures more predictable and reliable pagination behavior.

Curtis Chau
Curtis Chau
  Chat with engineering team now
Technical Writer

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.

...

Read More
Ready to Get Started?
Nuget Downloads 16,901,161 | Version: 2025.12 just released