Page setup
Set the page size, orientation, and margins with options or CSS @page rules, and give some content its own named pages.
Pass size, landscape, and margin to render(), or write a @page rule in your CSS, which wins over the options.
import { } from "takumi-pdf";
const = await (, {
: "letter", // a page keyword, or { width, height } in CSS px at 96 dpi
: true,
: { : 48, : 32, : 48, : 32 },
});| Option | Type | Default | Description |
|---|---|---|---|
size | a page keyword or { width, height } | "a4" | Page size in CSS px at 96 dpi. 1 |
landscape | boolean | false | Swaps page width and height, including explicit sizes. |
margin | number, "auto", or { top?, right?, bottom?, left? } | "auto" | Margin in CSS px. 2 |
backgroundColor | CSS color | unset | Fills the whole page, margins included, under everything. 3 |
1 Size keywords ignore case.
2 A side left out of the object is "auto".
3 Without backgroundColor, viewers show the page as white.
Each keyword is a portrait paper size:
| Keyword | Size | Keyword | Size |
|---|---|---|---|
"a3" | 297 × 420 mm | "jis-b4" | 257 × 364 mm |
"a4" | 210 × 297 mm | "jis-b5" | 182 × 257 mm |
"a5" | 148 × 210 mm | "ledger" | 11 × 17 in |
"b4" | 250 × 353 mm | "legal" | 8.5 × 14 in |
"b5" | 176 × 250 mm | "letter" | 8.5 × 11 in |
Automatic margins
| Side | "auto" resolves to |
|---|---|
| Top, bottom | The header or footer height plus a 20px inset, and at least 37.8px (1cm) |
| Left, right | 37.8px |
On a page one inch or smaller along an axis, automatic margins on that axis are 0. To set a numeric margin that fits a band, see Sizing the margin.
@page rules
A @page rule in css or a <style> element sets the page size and margins. It wins over size, landscape, and margin, as CSS does in Chromium with preferCSSPageSize. :first styles the first page, and :left and :right style pages by the side they fall on. The first page is a right page, or a left page when the root element has direction: rtl.
@page {
size: A5;
margin: 10mm;
}
@page :first {
margin-top: 30mm;
}
@page :left {
margin-left: 25mm;
}
@page :right {
margin-right: 25mm;
}sizetakesauto, one or two lengths, a keyword from the table above,portrait, orlandscape.- A margin percentage is a share of the page height for the top and bottom margins, and of the page width for the left and right.
margin: autois 0 on a page that fills its sheet, as in Chromium. To leave room for a band, leave that side out of the rule so the"auto"option applies.- A rule whose margins leave no page area is ignored. A header or footer that leaves no page area fails the render, as it does with the
marginoption. em,rem, andvar()read the root element's font size and custom properties.vwandvhread the page the options give, beforesizechanges it.
The rule also styles the page itself, as it does in Chromium:
backgroundcovers the whole page, margins included.borderandpaddinglie inside the margins, around the area the content flows in.widthandheightsize the page's box. Withautomargins a smaller box is centered on the page. With fixed margins the page takes the size the box and its margins add up to.box-sizingisborder-boxhere, as it is for every takumi element, sowidthandheightinclude the border and padding. Chromium measures the area inside them unless the rule setsbox-sizing: border-box. Setbox-sizing: content-boxto size the area as Chromium does.- The properties that inherit, such as
fontandcolor, pass to the page-margin boxes.
@page {
size: A4;
margin: 15mm auto;
width: 150mm;
box-sizing: content-box;
padding: 5mm;
border: 0.5pt solid #94a3b8;
background: #f8fafc;
}A background on <html> or <body> covers that element's box, not the page as it does in a browser. Set the page's color with @page { background } or the backgroundColor option.
Rules nested in @page, such as @top-center, draw page-margin boxes. Other descriptors, such as marks and bleed, are not read.
Named pages
The page property puts an element on a named page, which @page rules with that name style. An element on a different named page than the content before it starts a new page, and its children stay on that page type unless they name their own. Content without a page goes back to the unnamed pages.
@page wide {
size: A4 landscape;
margin: 10mm;
}
.wide-table {
page: wide;
}@page wide:first styles the first page of the document when it is a wide page, as :first does for unnamed pages. A name without a rule of its own takes the unnamed pages' rules.
Last updated on