dompdf Page break if element is exceeding page height?

dompdf Page break if element is exceeding page height?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

dompdf Page break if element is exceeding page height?

When working with dompdf, handling overflow content is a persistent pain point. The core issue you are facing stems from how the engine processes CSS properties versus its internal layout algorithm. Specifically, setting page-break-before: always or auto on a parent container like a table often fails to prevent the element from spilling over because dompdf prioritizes rendering the content flow before enforcing strict page boundaries in certain contexts. If you apply these rules and the table still breaks in the middle of rows, it is usually because the browser engine (or the DOMPDF renderer) interprets the break hint as a suggestion rather than an absolute constraint when calculating vertical space.

The standard CSS approach suggested for forcing a break before an element—such as page-break-before: always inside a container with overflow-x: visible or similar—is frequently ineffective within dompdf. Unlike browser-based rendering where the DOM tree is fully constructed and styles applied sequentially, dompdf often processes layout in passes that can overlook these hints if the content calculation does not explicitly account for the remaining page height. Consequently, relying solely on CSS properties like break-before or break-inside is insufficient when you need to guarantee that a specific block of data starts on a fresh page.

To achieve the behavior where a section only renders if it fits entirely within the current page, you must switch from a purely CSS-driven solution to a structural one. The most robust method involves splitting your HTML document into multiple distinct files and configuring dompdf to concatenate them sequentially. This approach bypasses the need for complex overflow calculations because each file represents a self-contained unit of content that starts at the top of a logical page.

Here is how you can structure this logic:

// Example PHP logic for splitting content
$content1 = $this->getSectionContent('header');
$content2 = $this->getSectionContent('body_part_1');
$content3 = $this->getSectionContent('body_part_2');

$dompdf->loadHtml($content1); 
$dompdf->render();
$dompdf->savePdf("output.pdf", true, "page1"); // Note: dompdf doesn't natively concatenate in one call easily without helper libraries

// Instead, a common pattern is to load each section into separate PDFs and merge them.

In practice, the cleanest implementation often involves using a library like barryvdh/laravel-dompdf alongside a custom merger or simply generating multiple PDF files that are merged in memory before saving. The key is ensuring that the HTML for the "overflowing" section is generated as a separate document. When you split your HTML into distinct div sections or logical blocks, you can treat each block as an independent rendering unit.

If you stick to a single HTML file, you must manually calculate the available height and conditionally render content. This requires calculating the total height of your elements before rendering begins. If the sum exceeds the page height (typically around 794 points for A4 with standard margins), you would need to programmatically split the source HTML string at that specific point.

// Pseudo-code concept for dynamic splitting
$totalHeight = calculateTotalHeight($htmlContent);
if ($totalHeight > $pageHeight) {
    $splitPoint = findSplitPoint($htmlContent, $pageHeight);
    $topHalf = substr($htmlContent, 0, $splitPoint);
    $bottomHalf = substr($htmlContent, $splitPoint);

    // Render top half
    $dompdf->loadHtml($topHalf);
    
    // Render bottom half on next page (requires manual page break or merging)
}

However, this manual calculation is brittle because it relies on the renderer's internal metrics, which can vary based on font rendering and margin settings. The structural approach of loading separate HTML fragments into dompdf instances and merging them provides a deterministic result. This ensures that no element ever exceeds the page height because the content is physically separated before the PDF generation process begins.

While CSS hints like page-break-inside: avoid are useful for preventing tables or images from being cut in half, they cannot force a break if the content simply doesn't fit. Therefore, the trade-off is between maintaining a single HTML structure with complex logic versus splitting the data source. For applications requiring strict pagination guarantees, splitting the content into multiple logical files and merging them at runtime remains the most reliable strategy supported by the dompdf architecture.

Our network