Pagination

Content flows across pages at the width available inside the margins. Use CSS break properties to start chapters, keep related content together, and control how paragraphs split. Percentage heights do not resolve in this mode because the content has no fixed height.

Break properties

import { render } from "takumi-pdf";

const pdf = await render(
  <article>
    <h1 style={{ breakBefore: "page" }}>Chapter two</h1>
    <section style={{ breakInside: "avoid" }}>Keep this together.</section>
  </article>,
);

break-inside: avoid applies only when the box fits on a page. An oversized box can still split. Text lines, images, and transformed subtrees are kept together where possible.

Widows and orphans

A cut through a paragraph keeps at least orphans lines at the bottom of the page and widows lines at the top of the next. Both default to 2, like Chromium. Set them to 1 to allow lone lines:

import { render } from "takumi-pdf";

const pdf = await render(
  <article style={{ widows: 3, orphans: 3 }}>
    A long report body wraps into many lines across the page boundary.
  </article>,
);

Both properties inherit. If a paragraph is too short to satisfy both values, orphans takes priority. A paragraph moves to the next page when the current page cannot hold the required lines. A requirement larger than a full page is relaxed.

Split decorations

A box that crosses a page break slices its border and background by default. Set box-decoration-break: clone to give each fragment complete decorations:

import { render } from "takumi-pdf";

const pdf = await render(
  <section
    style={{
      border: "1px solid #d1d5db",
      borderRadius: 8,
      boxDecorationBreak: "clone",
    }}
  >
    Long content that continues on the next page.
  </section>,
);

Repeated table headers

Use <thead> for column headings that repeat on continuation pages. The header stays together, including its spacing before the first body row.

import { render } from "takumi-pdf";

const pdf = await render(
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Qty</th>
      </tr>
    </thead>
    <tbody>{rows}</tbody>
  </table>,
);

A header taller than a quarter of the page does not repeat, matching Chromium. A header cell whose rowspan reaches into the body suppresses repetition for that table. <tfoot> renders once, after the body.

Page ranges

pageRanges keeps only the listed pages, like a print dialog. Each entry is a 1-based page number or an inclusive span:

import { render } from "takumi-pdf";

const pdf = await render(<main>{rows}</main>, {
  pageRanges: [1, { from: 4, to: 8 }, { from: 12 }],
});

An unset from starts at the first page. An unset to runs to the last. Ranges that keep no page reject the render.

Layout and page counters still run over the whole document. A kept page shows the numbers it would in full output, so page 4 of 12 still reads "Page 4 of 12". Links and outline entries pointing at a dropped page are dropped with it.

Watermarks

position: fixed paints a box on every page. The box lays out against the page area. It stays outside the content column.

import { render } from "takumi-pdf";

const pdf = await render(
  <main>
    <div
      style={{
        position: "fixed",
        inset: 0,
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
      }}
    >
      <span style={{ fontSize: 96, color: "rgba(0,0,0,0.08)" }}>DRAFT</span>
    </div>
    <p>Long content that continues on the next page.</p>
  </main>,
);

Place the fixed box outside transformed or filtered ancestors. Those ancestors contain the box, so it paginates with them instead of repeating independently.

Use a negative z-index to place the watermark behind content. Set the page color through backgroundColor if the root background would otherwise cover the watermark.