Pagination

Content lays out once at unbounded height. It then splits into pages. Unsplittable atoms never straddle a cut. These atoms include text lines, images, and transformed subtrees. A cut inside an atom moves to its top. This matches browser print fragmentation.

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>,
);

A break-inside: avoid box taller than the page window cannot fit on a page. It stops participating in cut avoidance. Browsers apply the same rule.

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. When a paragraph is too short to satisfy both minimums, the orphans win, as in Chromium. A break that cannot keep the orphans moves the whole paragraph to the next page. A minimum that cannot fit the current page at all is dropped for that page, like break-inside: avoid on an oversized box.

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

A <thead> paints again at the top of every page its table continues onto, following css-tables-3 repeated headers. The band is monolithic: a page break never lands inside it, and the spacing to the first body row repeats with it.

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>
    {/* Centers the watermark inside each page area. */}
    <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>,
);

A transformed or filtered ancestor captures a fixed descendant. That descendant stays in flow and paginates with its ancestor.

A negative z-index paints the box under the content. A background on the root covers it, exactly as it does in a browser. Set the paper with backgroundColor instead, which paints under the box.