mPDF Manual – Paging

# Page breaks

You can force a page break anywhere in the document either by using HTML code or PHP:

<?php
$mpdf->AddPage();  You can define or change all page characteristics when you add the new page: • orientation • margins • numbering (on/off, style or suprress) • header/footer Note the special TOCpagebreak() or <tocpagebreak> which are like AddPage()/ AddPageByArray() and <pagebreak> whilst at the same time marking the position for a Table of Contents to be later inserted. CSS @page can also be used to define page breaks. ## Forcing Page Breaks You can set the CSS value for page-break-before to always | left | right for any block element (p, div, etc). This will force a page-break, but take care that any enclosing (outer) block elements will be ‘closed down’ and their characteristics lost. ## Avoiding Page Breaks mPDF has limited scope to control when automatic page-breaks occur, and does not have ‘widows’ or ‘orphans’ protection. ### page-break-inside You can set the CSS value for page-break-inside to avoid for any block element. mPDF will try to avoid a page-break within the block, but this only works across a maximum of 2 pages, and is not compatible with table autosize or table rotate ### “Keep-with-table” <?php$mpdf->use_kwt = true;    // Default: false



If set to true, mPDF will automatically set page-break-inside: avoid; for any H1-H6 header that immediately precedes a table, thus keeping the heading together with the table.

• automatically sets the table to fit on one page (i.e. table:page-break-inside: avoid) if it is a rotated table
• ignored when:
• columns on,
• page-break-inside: avoid for surrounding element,
• active Forms

### Tables

If a table has the property page-break-inside: avoid and will not fit on the page, mPDF tries to shrink it to fit - up to a maximum “shrink-factor” set by the variable $mpdf->shrink_tables_to_fit - default is 1.4 (i.e. about 70% original size). If this still does not fit, it moves it to the next page. A shrunk table may not be what you want. You can prevent this resizing either by setting the maximum shrink-factor for a particular table e.g. <table autosize="1"> or by setting the variable for the whole document i.e. $mpdf->shrink_tables_to_fit = 1;

(Note that mPDF will always resize tables if it is the only way to fit a row or whole table onto a full page.)

See the documentation for Headers and Footers.

## Types of page break

The handling of borders and padding at page breaks was updated in mPDF 6.0. mPDF has three types of page breaks:

1. “slice” - no border and no padding are inserted at a break. The effect is as though the element were rendered with no breaks present, and then sliced by the breaks afterward

2. “cloneall” - each page fragment is independently wrapped with the borders and padding of all open elements.

3. “clonebycss” - open elements which have the (custom) CSS property box-decoration-break set to clone are independently wrapped with their border and padding.

The difference between 2) and 3) is illustrated by this example:

<style>
div { border: 1px solid black; padding: 1em; }
.level1 { box-decoration-break: slice; }
.level2 { box-decoration-break: clone; }
.level3 { box-decoration-break: clone; }
</style>

<div class="level1">
<div class="level2">
<div class="level3">
...
....
</div>
</div>
</div>



At the forced pagebreak which occurs after the P element:

If the page break type is “cloneall” - the three DIV elements will all be closed, by drawing the border and padding for each at the end of the page; the three DIV elements will be re-opened, drawing the borders and padding, at the top of the next page.

If the page break type is “clonebycss” - starting from the innermost element (div.level3) the DIV elements will have a border and padding at the end of the page if box-decoration-break is clone. In this case level 2 and level 3 will be closed/cloned and level 1 will be sliced; the opposite will occur at the top of the next page.

### Control of page breaks

 Automatic page breaks (in flow of text) Always "slice"  Always "cloneall"  Always "slice" If using columns Always "cloneall" Page break forced by change of @page selector Always "cloneall"  Always “cloneall” if a change in page size or margins is specified. Otherwise page break type is determined by value of configurable variable: $this->defaultPagebreakType. Default is “cloneall”. Default can be overridden by attribute page-break-type e.g.  Page breaks forced by: page-break-before or page-break-after Page break type determined by value of configurable variable: $this->defaultPagebreakType. Default is “cloneall”.

### Notes on page breaking

• box-decoration-break: slice|clone was proposed for CSS3 in http://www.w3.org/TR/2012/CR-css3-background-20120417/#the-box-decoration-break but it appears that it may be withdrawn. Default is slice; it is not inherited.
• page-break-before is not supported on <table>.
• page-break-before|after is ignored if set on block elements inside a table.
• Background images and gradients are not sliced (always cloned).