Skip to main content
Forme’s layout engine is page-native. Every layout decision, from flex calculations to text wrapping, is made with the page boundary as a hard constraint. This page explains how content flows across pages and how to control that behavior.

​
Why CSS page breaks are unreliable

If you have tried generating PDFs from HTML, you have probably run into this: you add page-break-inside: avoid or break-before: always to your CSS, and the browser ignores it. This is not a bug in your code. CSS page break properties (page-break-inside, break-before, break-after) are hints to the rendering engine, not guarantees. Chrome and other browsers frequently ignore them, especially with complex layouts, flexbox containers, or tables. This is a fundamental limitation of the HTML-to-PDF approach. The browser lays out content for a scrollable viewport, then tries to slice it into pages after the fact. Page breaks are an afterthought, not a first-class concern. Forme does not use CSS for layout. Every element is measured and positioned in a page-aware coordinate system. When content exceeds the page boundary, the engine splits it deterministically. There is no guessing, no hoping, and no browser-specific behavior to work around.

​
Automatic page breaks

When content exceeds the available space on a page, Forme automatically moves it to a new page. This happens at natural boundaries:
  • Between children of a View container
  • Between rows of a Table
  • Between lines of a Text block
You do not need to calculate page heights or manually manage pagination. The engine handles it.

​
Manual page breaks

Use <PageBreak /> to force content onto a new page:
You can also use the breakBefore style property:

​
Non-breakable elements

Set wrap={false} on a View to prevent it from splitting across pages. If the element doesn’t fit on the current page, it moves entirely to the next page.
This is useful for cards, summary blocks, and other elements where splitting would look wrong.

​
Widow and orphan control

When a text paragraph splits across pages, Forme ensures a minimum number of lines appear on each side of the break. This prevents a single isolated line at the bottom of a page (orphan) or at the top of the next page (widow). By default, at least 2 lines are kept on each side. You can adjust this per element:
If only 1 line would fit at the bottom of a page (and minOrphanLines is 2), the entire paragraph moves to the next page. If a split would leave only 1 line at the top of the next page (and minWidowLines is 2), the split point moves up to keep at least 2 lines on the next page.

​
Fixed headers and footers

Use <Fixed> to repeat content on every page. Fixed elements reduce the available content area.
Fixed elements appear in the page margin area (between the page edge and the content boundary). They are drawn on every page that the parent <Page> produces.

​
Full example: header, footer with page numbers, and content

The header and footer repeat on every page automatically. The content area between them is reduced accordingly, so you don’t need to calculate available space.

​
Watermarks

For text that appears behind content on every page, use the <Watermark> component instead of <Fixed>:

​
Dynamic page numbers

Use these placeholders in any <Text> element:
Page numbers are resolved after the full layout pass, so {{totalPages}} is always accurate. These are commonly used inside <Fixed> elements but work anywhere.

​
Table header repetition

When a table spans multiple pages, header rows (marked with header) are automatically repeated at the top of each continuation page.
No configuration needed. Mark a row as header and it repeats automatically.

​
Flex layout across page breaks

This is the core differentiator from other PDF tools. When a flex container splits across pages, Forme runs independent flex calculations for each page fragment. Consider a row layout with three items where the container splits after the second item:
In Forme, each page fragment gets its own flex pass. Items on page 1 fill that page’s width correctly, and items on page 2 fill that page’s width correctly. In tools that use the infinite-canvas-then-slice approach, flex runs once on the full container, then the result is sliced. This produces incorrect widths on both pages because the flex math assumed all items were on one line.

​
A row that crosses a page keeps its columns

A flexDirection: 'row' taller than the space left on the page continues as parallel columns on every page it spans. Each column carries on beneath itself on the next page, in its own track:
A two-column layout stays two columns on page 2. The alternative — laying the first column out until it runs out of room, then starting the second wherever that ended — leaves the first page half empty and stops the design being a two-column design at all. This applies to wrapped rows (flexWrap: 'wrap') as well, since 0.24.0. Three details worth knowing:
  • A row that does not fit starts anyway. It begins in the space that is there and continues overleaf, rather than moving to the next page whole and abandoning what was left. Each column’s own widow and orphan control decides whether its first line is worth placing, so a column with room for one stranded line pushes that line instead.
  • alignItems: 'stretch' continues the band. A column whose content ends before its neighbour’s still paints its background and borders down every page the row crosses, the way a browser does, rather than stopping where its text ran out.
  • A fixed height is honoured across the boundary. A box with height: 500 that has only 130pt of page left paints 130pt on that page and the remaining 370 on the next, instead of shrinking to its content.

​
How it differs from react-pdf

react-pdf lays out content on an infinite vertical canvas and then slices it into pages. This causes several problems:
  1. Flex breaks on page boundaries. A flex row that gets sliced has its distribution calculated for the full container, then cut in half. Both halves have wrong proportions.
  2. Tables break mid-row. Without page-aware row placement, a table row can be sliced between its top and bottom border.
  3. No header repetition. Since the table is just a set of rectangles on an infinite canvas, there is no concept of “repeat this row at the top of each page.”
  4. No post-split adjustment. After slicing, there is no second layout pass to fix the fragments. What you see is the result of a single layout pass on the wrong dimensions.
Forme avoids all of these problems because the page is the fundamental unit of layout. Every decision is made with the page boundary in mind from the start.