Page Breaks in HTML to PDF Conversion

Jonas, CTO

When it comes to generating PDF files, there are numerous libraries available for various programming languages. If your PDF generation requirements are simple and don't involve complex designs, using a native PDF generation library is a reasonable choice. These libraries offer good performance and simplicity. However, creating visually appealing and dynamically structured layouts can be challenging, and mastering them often requires a steep learning curve.

ConvertAPI's HTML to PDF converter provides an alternative solution for generating beautiful PDFs with dynamic content layouts, without the need to learn new tools or libraries. Leveraging the battle-tested HTML and CSS, you can easily utilize your existing knowledge in these technologies to create stunning PDFs. Whether you are already familiar with modern HTML and CSS or are learning them for the first time, these skills will prove useful in many future scenarios.

Challenges in HTML to PDF Conversion

Most HTML documents are primarily designed for web browsers, with little consideration given to printing. As society becomes increasingly conscious of environmental impact, fewer websites prioritize designing for printing. Additionally, digital formats have largely replaced physical paper documents, thanks to the prevalence of portable devices like tablets and smartphones.

HTML, by nature, is optimized for displaying documents across various screen sizes and adapting content accordingly. However, this flexibility brings disadvantages when a document needs to be consistently displayed across devices and contained within a single file. This is where the Portable Document Format (PDF) comes into play.

PDF viewers are often simpler and lighter compared to modern web browsers. PDF ensures that document pages remain exactly as designed, irrespective of the viewing device. However, converting HTML to PDF introduces a set of challenges.

Splitting HTML into Pages

HTML does not provide a specific tag to split a document into pages. Instead, CSS offers a set of properties designed explicitly to control page breaks. These properties enable developers to have fine-grained control over the layout of printed documents. Here are some of the most commonly used page break properties:

1. break-before and break-after

The page-break-before and page-break-after properties define whether a page break should occur before or after an element. These properties accept values such as auto, always, avoid, and left or right for controlling the positioning of page breaks.

2. break-inside

The page-break-inside property determines whether an element should be split across multiple pages or kept intact on a single page. By setting this property to avoid, you can ensure that an element remains together on a single page, which is particularly useful for maintaining the integrity of tables, images, or other content that should not be fragmented.

3. orphans and widows

The orphans and widows properties deal with the prevention of orphaned or widowed lines, which occur when the first or last line of a paragraph is left alone on a page. By setting these properties to appropriate values, you can control the minimum number of lines that should be visible before or after a page break, thus avoiding these unsightly typographic issues.

Implementing Page Breaks in CSS

To implement page breaks in CSS, you need to target the specific elements that require controlled pagination and apply the appropriate page break properties. Here's an example:

.print-page {
  break-before: always;

.avoid-page-break {
  break-inside: avoid;

In the example above, the .print-page class ensures that each element with that class will start a new page, forcing a page break before it. On the other hand, the .avoid-page-break class prevents any element it's applied to from being split across multiple pages.

Flexbox and the page breaks

The break-after property, which is used to control page and column breaks, does not work as expected within flexbox layouts due to the inherent nature of flexbox and the way it handles layout and space distribution. Here are the reasons why break-after does not function effectively within flexbox:

  1. Flexbox's Container-Based Layout Approach: Flexbox is designed to distribute available space among flex items within a container, allowing them to resize and reflow dynamically. It prioritizes maintaining flexibility and responsiveness, which means that the container adapts to the size of its contents rather than being divided into fixed pages or columns. As a result, the concept of page or column breaks conflicts with the fundamental principles of flexbox.

  2. Flexbox Overrides Breaks: The flex container's layout algorithm takes precedence over the break-after property. The purpose of flexbox is to create a flexible flow of items, ensuring they adjust to different screen sizes and orientations. Therefore, when break-after is applied to elements within a flex container, the breaks are often ignored to preserve the container's flexibility.

  3. Different Rendering Behaviors: Different browsers and their versions handle break-after within flex containers inconsistently. Some browsers may honor the break-after property, resulting in page or column breaks as intended, while others may completely ignore it. This inconsistency adds to the challenge of achieving consistent layouts across various browsers.

  4. Conflict of Objectives: Flexbox primarily focuses on the distribution of space and the arrangement of items within a container. On the other hand, the break-after property is concerned with controlling the flow of content across pages or columns. These two objectives often clash when used together, as they serve different purposes and have conflicting requirements.

Possible Workarounds: Although break-after may not work reliably within flexbox, there are some workarounds you can consider if you need to achieve specific page or column breaks within a flex container:

  1. Combination with Other Layout Techniques: You can combine flexbox with other layout techniques such as CSS Grid or floats to achieve the desired page or column breaks. By using these techniques selectively, you can create more complex layouts while still maintaining the flexibility and responsiveness provided by flexbox.

  2. Manual Content Splitting: Instead of relying on automatic breaks, you can manually split your content into separate sections and place them in different flex containers. This approach allows you to control the placement of breaks more precisely, albeit at the cost of additional markup and potential maintenance challenges.


While native PDF generation libraries are suitable for simple PDF requirements, ConvertAPI's HTML to PDF converter offers an alternative solution for creating visually appealing and dynamic PDFs using familiar HTML and CSS. Mastering the page break properties in CSS can help developers achieve fine-grained control over the layout of printed documents and ensure beautiful PDF outputs.

In conclusion, while there are challenges in implementing page breaks in HTML to PDF conversion, understanding the capabilities and limitations of CSS properties, exploring alternative layout techniques, and leveraging tools like ConvertAPI can empower developers to generate high-quality PDFs.