Pagination

Content lays out at the width inside the margins, then flows across pages. Use CSS break properties to start chapters, keep related content together, and control how paragraphs split.

The content has no fixed height, so percentage heights do not resolve. Viewport units do. vh is the height of the page area inside the margins, as in print.

Break propertiesCopy Anchor Link

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. A taller box still splits.

A text line, an image, or a transformed subtree never splits unless it is taller than a page.

Full-page boxesCopy Anchor Link

A 100vh box fills the page area, so the next box starts on the following page. Use it for a cover or any page laid out by hand:

import { render } from "takumi-pdf";

const pdf = await render(
  <article>
    <section style={{ height: "100vh", display: "flex", alignItems: "flex-end" }}>
      <h1>Annual report</h1>
    </section>
    <p>The report starts on page two.</p>
  </article>,
  { margin: 0 },
);

vw, vmin, and vmax resolve against the same page area. In the header and footer bands, viewport units resolve against the full page.

Widows and orphansCopy Anchor Link

When a page break cuts a paragraph, at least orphans lines stay at the bottom of the page and at least widows lines move to the top of the next. Both default to 2, like Chromium. Set them to 1 to allow single 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, orphans wins.
• A paragraph moves to the next page when the current page cannot hold the required lines.
• A requirement taller than a full page is relaxed.

Split decorationsCopy Anchor Link

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 and footersCopy Anchor Link

A <thead> repeats at the top of each continuation page. A <tfoot> repeats below the last row on every page the table breaks across. Each section stays in one piece, with its spacing next to the body.

import { render } from "takumi-pdf";

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

A section repeats only when all of these hold:

• It has break-inside: avoid. <thead> and <tfoot> set it by default, as in Chromium.
• It is no taller than a quarter of the page area, matching Chromium.
• None of its cells has a rowspan that reaches into the body.

Page rangesCopy Anchor Link

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. The render fails if a range names page 0, runs backwards, or keeps no page.

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

WatermarksCopy Anchor Link

A position: fixed box paints on every page. It lays out against the page area, outside the content flow.

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

Keep the fixed box outside transformed or filtered ancestors. Such an ancestor contains the box, so the box paginates with it instead of repeating on every page.

To put the watermark behind content, give it a negative z-index. If the root background then covers it, set the page color with the backgroundColor option instead.