TCPDF: HTML table and page breaks

TCPDF: HTML table and page breaks

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

Stefan Bogdanescu

Founder & Senior Architect

TCPDF: HTML table and page breaks

When rendering large datasets using TCPDF, the most frustrating issue isn't usually generating the PDF itself; it's how the engine handles page breaks within complex elements like HTML tables. The default behavior often results in an abrupt cut-off where a row is split between two pages, leaving empty cells on the second page that look broken or incomplete. This happens because TCPDF treats the table as a continuous flow of content until it hits a physical limit, at which point it simply chops the element to fit the remaining space.

To fix this automatically without manually calculating every single row height, you need to understand how TCPDF handles "breakable" versus "unbreakable" elements within its HTML renderer. The library provides specific properties for table rows that dictate exactly how they should be handled when a page break occurs.

The most direct solution is setting the empty and stretch attributes on the <tr> tag. When you set empty="true" (or omit it, as it defaults to true in many contexts), TCPDF reserves space for the remaining rows of the table on the next page rather than cutting them off abruptly. However, the attribute that actually controls the splitting behavior is stretch. By default, if a row cannot fit on the current page, TCPPDF will try to keep the entire row intact. If it fails, it moves the whole row to the next page, potentially leaving a large gap at the bottom of the current page.

If your goal is to allow a row to be split (which matches the default behavior shown in many tutorials but often looks ugly), you rely on the empty property handling the bottom whitespace. A more robust approach for maintaining visual integrity is to ensure the table structure explicitly tells the renderer to handle overflow gracefully. You can achieve this by setting stretch="false" on the <tr> tag if you want to force rows to move entirely to the next page, effectively preventing mid-row breaks but creating large white spaces. Conversely, leaving it default allows the row to break, but you must ensure your CSS or inline styles account for the potential discontinuity.

For scenarios where automatic calculation of remaining space is critical, TCPDF offers a more programmatic approach using the writeHTML method alongside custom logic, though this is often overkill for simple table rendering. The standard HTML attribute method remains the most efficient. You can apply these attributes directly in your PHP string or via Blade templates:

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Status</th>
        </tr>
    </thead>
    <tbody>
        <!-- Default behavior: row may split, empty space left below -->
        <tr>
            <td>Data 1</td>
            <td>Active</td>
        </tr>
        
        <!-- Force row to move entirely to next page if it doesn't fit -->
        <tr stretch="false">
            <td>Long Data That Might Not Fit</td>
            <td>Pending</td>
        </tr>
    </tbody>
</table>

In the example above, the first row is subject to standard breaking logic. The second row uses stretch="false", instructing TCPDF to not stretch the row content vertically but instead move the entire row to the next page if it exceeds the current height. This prevents the "split cell" look but introduces a layout shift where data appears on the next page rather than completing the thought on the current one.

There is no single magic switch that makes TCPDF automatically calculate perfect breaks without any gaps, as PDF rendering requires precise positioning of cells. The trade-off here is between visual continuity (allowing splits) and structural integrity (keeping rows intact). If you require strict row integrity where a record must never be split across pages, you must implement logic to detect the page height before adding rows or use the stretch attribute to enforce movement.

For complex reports involving hundreds of rows, relying solely on HTML attributes might not be enough if the content is dynamic. In such cases, consider breaking the data source into chunks that fit within a single A4 page before passing them to the TCPDF instance. This reduces the complexity of handling mid-page breaks and gives you full control over where new pages start.

Our network