Splitting
How Format breaks an item across page boundaries when it doesn't fit whole.
When the next item in a Flow's stream doesn't fit on the current page, Format tries to break it instead of deferring the whole thing. The Flow's splitGranularity field sets where a break is allowed. Format places whatever fits on the current page and defers the rest to the next.
Split granularity
Every Flow has a splitGranularity that sets how finely its items may break. The default is none: Format keeps each item whole, and an item that doesn't fit moves whole to the next page. A finer granularity lets Format break items at sentence, word, or grapheme boundaries, so more fits on each page. The field does not inherit. A Flow that leaves it unset uses none, whatever the enclosing Flow or the Layout sets.
| Split granularity | What it does |
|---|---|
none (default) | No splitting. An item that doesn't fit is deferred whole. The field does not inherit. |
sentence | Break at sentence boundaries, using Unicode-aware segmentation. |
word | Break at word and line-break opportunities, using Unicode-aware segmentation. |
grapheme | Break at grapheme clusters, the finest granularity. May break mid-word. |
Choose a finer granularity only when breaking won't change the content's meaning. That depends on the structure of your content and your Layout design.
What survives a split
When an item breaks across pages, Format repeats the surrounding markup so each page renders cleanly.
- Nested-flow scaffolding repeats. When a nested Flow breaks, its scaffolding (
<section>,<tr>, and the like) appears on both pages. Only the stream's items split across them. - Flow scaffolding repeats. Markup around the Stream (table headers, list wrappers, and so on) appears on every page the Flow reaches. See Scaffolding.
- Layout scaffolding repeats. The Layout's per-page markup (headers, footers, and the rest) appears on each new page.
Only the items at the Stream position break. Everything around them repeats, so each page is a valid render of the Layout.
Per-Flow granularity
Each Flow declares its splitGranularity once, and that value applies to the items in its stream. A nested Flow declares its own splitGranularity rather than taking the surrounding Flow's, so one block of content can break at a different granularity from the rest of the page.
When no useful split is possible
When the granularity allows breaking, Format searches for the break point that puts the largest head on the current page, testing progressively larger and smaller head and tail pairs. When the granularity is none, or when no break point produces a head that fits, Format defers the whole item to the next page.
The empty-page exception
Deferring an item doesn't always make progress. Picture the first item Format tries to place in a Flow on a fresh page: it won't break, no other flow has placed anything on the page yet, and so deferring it would leave the page empty. The next page would present the same item in the same Flow with nothing else to place, and deferring again would repeat forever.
To break the cycle, Format places the item on the page instead of deferring it, then stops filling that Flow. The next item in the stream continues on the page after. The placed item can be taller than the page, in which case it runs past the page edge. Whether the overflow shows or gets cut off is up to your CSS: set overflow: hidden on the surrounding element to clip it.
This is a last-resort behavior. To avoid it, set a finer splitGranularity on the Flow, or wrap the content in a nested Flow so breaking can happen inside it.
Picking the right granularity
Keep none, the default, for items that should stay intact: invoice line items, profile cards, image-and-caption pairs, or code blocks, anything where the item is conceptually atomic and breaking it would lose meaning.
Choose sentence for content where the sentence is the natural unit and a break inside one would read awkwardly: legal clauses, terms and conditions, or formal documents where each sentence carries a discrete idea.
Apply word to prose-heavy documents such as letters, articles, books, and reports, where readers expect content to flow continuously across pages. The result reads like a printed book, with each page filled to its edge.
Save grapheme for content where you can't rely on word boundaries: long unbroken strings like URLs or hex blobs, or languages without clear word separators such as Chinese or Japanese. A grapheme break can fall mid-word.