Page breaks in mPDF

Written for mPDF 8.2 on PHP 8.1+. Updated 2 November 2026.

mPDF breaks pages automatically when content fills the page. There are three ways to control it yourself.

1. The <pagebreak> tag

<p>End of chapter one.</p>
<pagebreak />
<h2>Chapter two</h2>

The tag takes attributes that change the following pages:

<pagebreak orientation="L" />                        <!-- landscape from here -->
<pagebreak sheet-size="A3" />                        <!-- different paper size -->
<pagebreak margin-top="40" margin-bottom="20" />    <!-- new margins, in mm -->
<pagebreak resetpagenum="1" />                       <!-- restart page numbering -->

2. CSS

h2 { page-break-before: always; }
.summary { page-break-after: always; }
table.keep { page-break-inside: avoid; }

page-break-before and page-break-after work on block elements. page-break-inside: avoid is honoured on tables: mPDF moves the whole table to the next page if it fits there. Very tall tables still break, because there’s nowhere else for them to go.

3. From PHP

$mpdf->WriteHTML($coverHtml);
$mpdf->AddPage();                 // same settings
$mpdf->AddPage('L');              // landscape page
$mpdf->WriteHTML($chapterHtml);

Building a document section by section with several WriteHTML() calls and AddPage() between them is also gentler on memory (see performance).

Keeping headings with what follows

A heading stranded at the bottom of a page looks careless. For headings that sit right before a table, set $mpdf->use_kwt = true; (“keep with table”) and mPDF moves them along with the table. For other content, wrap the heading and its first paragraph in a table with page-break-inside: avoid.

Table rows

mPDF doesn’t split a single table row across pages unless the row is taller than a page. Long tables break between rows, and a thead repeats on the next page automatically.