IronSoftware

Posted on Jan 22

HTML to PDF Page Breaks in C# (.NET Guide)

#dotnet #csharp

Page breaks control where PDF pages split. Force breaks before sections, prevent awkward splits in the middle of tables, and keep images intact across pages.

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

var renderer = new ChromePdfRenderer();

var html = @"
<h1>Chapter 1</h1>
<p>Content...</p>

<div style='page-break-before: always;'>
    <h1>Chapter 2</h1>
    <p>Starts on new page...</p>
</div>";

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("chapters.pdf");

CSS page-break properties work exactly as they do in print stylesheets.

How Do I Force a Page Break?

Use page-break-before or page-break-after:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    .new-page-before { page-break-before: always; }
    .new-page-after { page-break-after: always; }
</style>

<h1>Section 1</h1>
<p>This content is on page 1.</p>

<div class='new-page-before'>
    <h1>Section 2</h1>
    <p>This starts on a new page.</p>
</div>

<div class='new-page-after'>
    <h1>Section 3</h1>
    <p>Content here, then page break follows.</p>
</div>

<h1>Section 4</h1>
<p>This is on yet another page.</p>";

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("sections.pdf");

How Do I Prevent Elements from Splitting?

Use page-break-inside: avoid to keep elements intact:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    .no-split {
        page-break-inside: avoid;
    }

    .card {
        border: 1px solid #ddd;
        padding: 20px;
        margin: 10px 0;
        page-break-inside: avoid;
    }
</style>

<div class='card'>
    <h2>Card Title</h2>
    <p>This entire card stays on one page.</p>
    <p>If it doesn't fit, it moves to the next page.</p>
</div>";

var pdf = renderer.RenderHtmlAsPdf(html);

The element moves to the next page if it can't fit completely.

How Do I Keep Tables Together?

Tables often split awkwardly. Prevent it:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    /* Keep entire table on one page if possible */
    .keep-together {
        page-break-inside: avoid;
    }

    /* Keep rows from splitting */
    table {
        page-break-inside: auto;
    }

    tr {
        page-break-inside: avoid;
        page-break-after: auto;
    }

    /* Repeat header on each page for long tables */
    thead {
        display: table-header-group;
    }

    tfoot {
        display: table-footer-group;
    }
</style>

<div class='keep-together'>
    <table>
        <thead>
            <tr><th>Product</th><th>Price</th></tr>
        </thead>
        <tbody>
            <tr><td>Widget A</td><td>$10</td></tr>
            <tr><td>Widget B</td><td>$15</td></tr>
            <!-- More rows... -->
        </tbody>
    </table>
</div>";

var pdf = renderer.RenderHtmlAsPdf(html);

The thead repeats on each page for long tables.

How Do I Keep Images from Splitting?

Wrap images to prevent partial cuts:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    .image-container {
        page-break-inside: avoid;
    }

    .figure {
        page-break-inside: avoid;
        text-align: center;
        margin: 20px 0;
    }

    .figure img {
        max-width: 100%;
        height: auto;
    }

    .figure figcaption {
        font-style: italic;
        margin-top: 10px;
    }
</style>

<div class='figure'>
    <img src='chart.png' />
    <figcaption>Figure 1: Sales Growth</figcaption>
</div>";

var pdf = renderer.RenderHtmlAsPdf(html);

The image and caption stay together.

How Do I Control Orphans and Widows?

Avoid single lines stranded at page breaks:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    p {
        orphans: 3;  /* Min lines at bottom of page */
        widows: 3;   /* Min lines at top of page */
    }

    h1, h2, h3 {
        page-break-after: avoid;  /* Keep headings with content */
    }
</style>

<h2>Section Title</h2>
<p>This paragraph will have at least 3 lines before a page break
and at least 3 lines after, preventing awkward single-line splits.</p>";

var pdf = renderer.RenderHtmlAsPdf(html);

How Do I Create Chapter Breaks?

Structured document with chapters:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    .chapter {
        page-break-before: always;
    }

    .chapter:first-child {
        page-break-before: auto;  /* No break before first chapter */
    }

    .chapter h1 {
        margin-top: 0;
        page-break-after: avoid;
    }
</style>

<div class='chapter'>
    <h1>Chapter 1: Introduction</h1>
    <p>Opening content...</p>
</div>

<div class='chapter'>
    <h1>Chapter 2: Background</h1>
    <p>Historical context...</p>
</div>

<div class='chapter'>
    <h1>Chapter 3: Analysis</h1>
    <p>Main discussion...</p>
</div>";

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("book.pdf");

How Do I Handle Print-Specific Styles?

Use media queries for PDF-specific styling:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    /* Screen styles */
    .sidebar { display: block; }
    .print-only { display: none; }

    /* Print/PDF styles */
    @media print {
        .sidebar { display: none; }
        .print-only { display: block; }

        .page-break { page-break-before: always; }

        body {
            font-size: 12pt;
            line-height: 1.5;
        }

        a[href]:after {
            content: ' (' attr(href) ')';
            font-size: 10pt;
        }
    }
</style>

<div class='sidebar'>Navigation (hidden in PDF)</div>
<div class='print-only'>Printed Version</div>

<h1>Main Content</h1>
<p>This appears in both web and PDF.</p>";

var pdf = renderer.RenderHtmlAsPdf(html);

How Do I Create Invoice Page Breaks?

Practical invoice layout:

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

var renderer = new ChromePdfRenderer();

var html = @"
<style>
    .invoice-header {
        page-break-inside: avoid;
        margin-bottom: 20px;
    }

    .line-items {
        page-break-inside: auto;
    }

    .line-items tr {
        page-break-inside: avoid;
    }

    .invoice-footer {
        page-break-inside: avoid;
    }

    .signature-section {
        page-break-before: always;  /* Signature on separate page */
    }
</style>

<div class='invoice-header'>
    <h1>Invoice #12345</h1>
    <p>Date: 2024-01-15</p>
</div>

<table class='line-items'>
    <thead>
        <tr><th>Item</th><th>Qty</th><th>Price</th></tr>
    </thead>
    <tbody>
        <!-- Items here -->
    </tbody>
</table>

<div class='invoice-footer'>
    <p><strong>Total: $1,234.56</strong></p>
</div>

<div class='signature-section'>
    <h2>Authorization</h2>
    <p>Signature: _________________</p>
</div>";

var pdf = renderer.RenderHtmlAsPdf(html);

How Do I Debug Page Breaks?

Add visual markers to see where breaks occur:

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

var renderer = new ChromePdfRenderer();

// For debugging, add visible markers
var html = @"
<style>
    .debug-break {
        border-top: 2px dashed red;
        padding-top: 10px;
        margin-top: 10px;
    }

    .debug-break::before {
        content: '--- PAGE BREAK ---';
        color: red;
        font-size: 10px;
    }

    /* Actual page break */
    .page-break {
        page-break-before: always;
    }
</style>

<p>Content before break...</p>

<div class='page-break debug-break'>
    <p>Content after break...</p>
</div>";

// Remove debug styles for production
var productionHtml = html.Replace("debug-break", "");

Quick Reference

CSS Property	Effect
`page-break-before: always`	Force break before element
`page-break-after: always`	Force break after element
`page-break-inside: avoid`	Prevent element from splitting
`orphans: N`	Min lines at page bottom
`widows: N`	Min lines at page top

Common Patterns	Use Case
Chapter starts	`page-break-before: always`
Keep card intact	`page-break-inside: avoid`
Table rows	`tr { page-break-inside: avoid }`
Headings	`h2 { page-break-after: avoid }`
Signatures	Separate page with `page-break-before`

Page breaks give you print-ready control over document layout. Use CSS to create professional multi-page PDFs.

For more page break options, see the IronPDF page breaks documentation.

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

DEV Community