Flow

A Flow is a region whose content paginates across pages. Everything inside a Flow that is not its Stream is scaffolding that repeats on every page the content reaches; the stream's items appear once and flow.

Author the stream two ways. A bare Flow takes its own children as the stream, injected with no wrapper. A scaffolded Flow wraps the stream in a Stream inside surrounding markup, so a table's header and footer, or a panel's heading, repeat on each page while the rows or items flow.

Flows nest. A Flow placed inside another Flow's stream paginates against the nearest enclosing Frame, or the page when there is none, and its own scaffolding repeats on each page its content reaches.

Example

A scaffolded Flow: a <table> whose header and footer repeat on every page while the rows stream in. The Stream marks where the rows land.

export const doc = () => (
	<Document title='Invoice #1234'>
		<Layout id='invoice' width={793.71} height={1122.52}>
			<Flow>
				<table>
					<thead>
						<tr><th>Item</th><th>Qty</th></tr>
					</thead>
					<tbody>
						<Stream>
							<tr><td>Design work</td><td>1</td></tr>
							{/* ...more rows */}
						</Stream>
					</tbody>
					<tfoot>
						<tr><td>Subtotal</td><td>1</td></tr>
					</tfoot>
				</table>
			</Flow>
		</Layout>
	</Document>
)

<template>
	<Document title="Invoice #1234">
		<Layout id="invoice" :width="793.71" :height="1122.52">
			<Flow>
				<table>
					<thead>
						<tr><th>Item</th><th>Qty</th></tr>
					</thead>
					<tbody>
						<Stream>
							<tr><td>Design work</td><td>1</td></tr>
							<!-- ...more rows -->
						</Stream>
					</tbody>
					<tfoot>
						<tr><td>Subtotal</td><td>1</td></tr>
					</tfoot>
				</table>
			</Flow>
		</Layout>
	</Document>
</template>

<template data-type="document" data-title="Invoice #1234">
	<template data-type="layout" data-id="invoice" data-width="793.71px" data-height="1122.52px">
		<template data-type="flow">
			<table>
				<thead>
					<tr><th>Item</th><th>Qty</th></tr>
				</thead>
				<tbody>
					<template data-type="stream">
						<tr><td>Design work</td><td>1</td></tr>
						<!-- ...more rows -->
					</template>
				</tbody>
				<tfoot>
					<tr><td>Subtotal</td><td>1</td></tr>
				</tfoot>
			</table>
		</template>
	</template>
</template>

The <table>, <thead>, and <tfoot> are preserved on every page the Flow produces. Only the <tbody> rows inside the Stream paginate.

Authoring the stream

A Flow takes its stream two ways.

A bare Flow uses its own children as the stream. Format adds no wrapper element around them, so a Flow of paragraphs renders as those paragraphs, flowing across pages:

<Flow>
  <p>First paragraph.</p>
  <p>Second paragraph.</p>
</Flow>

<Flow>
  <p>First paragraph.</p>
  <p>Second paragraph.</p>
</Flow>

<template data-type="flow">
  <p>First paragraph.</p>
  <p>Second paragraph.</p>
</template>

A scaffolded Flow wraps the stream in a Stream inside surrounding markup, as in the table example above. The markup outside the Stream repeats on each page; the Stream's items flow.

Nesting

Flows nest. A Flow placed inside another Flow's stream paginates against the nearest enclosing Frame, or the page when no frame encloses it, and its own scaffolding repeats on each page its content reaches. Use a nested Flow when a section of repeating content sits inside another stream, such as a per-client panel whose heading repeats while its rows flow:

<Flow>
  <h1>Report</h1>
  <Flow>
    <section className='panel'>
      <h2>Findings</h2>
      <Stream>
        <p>Finding one.</p>
      </Stream>
    </section>
  </Flow>
</Flow>

<Flow>
  <h1>Report</h1>
  <Flow>
    <section class="panel">
      <h2>Findings</h2>
      <Stream>
        <p>Finding one.</p>
      </Stream>
    </section>
  </Flow>
</Flow>

<template data-type="flow">
  <h1>Report</h1>
  <template data-type="flow">
    <section class="panel">
      <h2>Findings</h2>
      <template data-type="stream">
        <p>Finding one.</p>
      </template>
    </section>
  </template>
</template>

Usage

A Flow is the region that paginates. Everything a Layout shows that needs to break across pages goes in a Flow; everything that should reprint on every page stays outside one, as Layout scaffolding.

Multiple Flows in one Layout

Declare more than one Flow in a Layout when the page has independent content streams that each break page to page. A two-column page where the body and a sidebar paginate on their own is two Flows. Each fills against its own region.

Picking the splitGranularity

The splitGranularity field controls whether content can break across a page boundary, and how finely. It does not inherit: when unset, a Flow uses the default none, which keeps each item whole and moves one that doesn't fit to the next page. For which value to pick, see Splitting.

Pagination strategy

The paginationStrategy field chooses whether a Flow breaks on overflow (auto) or only at PageBreak markers (manual). A top-level Flow uses its own value when set, falls back to the Layout's, then defaults to auto. Inside a nested Flow the parent Flow's strategy applies and any value set on the nested Flow is ignored, so a stream and the flows inside it break the same way.

Numbering scope

Set scope to a counter name to open a numbering scope of that name around the Flow's content. A counter of that name nested inside the Flow restarts at each Flow instance, so each Flow numbers its own section from the start.

Constraints

• Scaffolding repeats; the stream flows. Everything inside a Flow that is not its Stream reprints on every page the content reaches.
• A bare Flow has no Stream. Its own children are the stream. Add a Stream only when scaffolding must wrap the items.
• A nested Flow overflows against the nearest ancestor Frame, or the page when none encloses it.
• A nested Flow and a PageBreak must each be a direct item of the parent Flow's stream. Buried in other content, such as inside an <ol> or a table cell, the marker renders nothing and Format reports it as a misplaced marker in the document summary.

Related

• Stream
• Frame
• Pagination
• Splitting
• Scaffolding