Pages and pagination
Page size and margins
<x-doc::page size="letter" orientation="landscape" margin="0.7in 0.8in">
…
</x-doc::page>use Quoin\{Document, Page, Text};
use function Quoin\in;
$document = Document::make(
Page::letter()->landscape()->margin(in(0.7), in(0.8))->body(Text::make('…')),
);The named sizes are a0 to a6, b4, b5, letter, legal, tabloid and executive (Page::sizeNames() returns the list). In PHP, the common ones have shortcuts (Page::a4(), a3(), a5(), a6(), letter() and legal()), Page::named('tabloid') covers the rest, and Page::size($width, $height) takes any custom size. In Blade, write a custom size as size="210mm 297mm" (or size="8.5in 14in").
Use whichever of letter (8.5 × 11 in) and a4 (210 × 297 mm) suits your readers. Lengths take any unit (pt, mm, cm, in or px), so 20mm and 0.8in are equally valid margins. The examples in this guide mix US Letter with inches and A4 with millimeters; swap one for the other wherever you like.
Margins that meet or cross, leaving no room for content, throw InvalidValue when you export.
Headers, footers and backgrounds
A header, footer or background is repeated on every page, and the body content flows in the space between them.
<x-doc::page>
<x-slot:header>
<x-doc::text size="8pt" color="slate-500">Quarterly report</x-doc::text>
</x-slot:header>
…body…
<x-slot:footer>
<x-doc::page-number format="Page {page} of {total}" align="right" size="8pt" />
</x-slot:footer>
</x-doc::page>use Quoin\{Column, Document, Page, PageNumber, Row, Spacer, Text};
use function Quoin\{mm, pt};
$body = [];
for ($i = 1; $i <= 80; $i++) {
$body[] = Text::make("Paragraph $i. " . str_repeat('Lorem ipsum dolor sit amet. ', 6));
}
$document = Document::make(
Page::a4()->margin(mm(20))
->header(Text::make('Quarterly report')->color('slate-500')->size(pt(8)))
->footer(Row::make(Spacer::flex(), PageNumber::make('Page {page} of {total}')->size(pt(8))))
->body(Column::make(...$body)->gap(pt(6))),
);In the page number format, {page} is the current page and {total} is the total page count. The total is filled in after layout, so it's always correct. To change the space between the body and the header or footer, set header-gap or footer-gap on the page.
First-page and even-page headers
A page can have a different header and footer on its first page, and on its even pages. Set them next to the normal ones. Each takes the same content as header() and footer().
A letterhead on page 1
The first page shows the letterhead, and every page after it shows a short running title.
<x-doc::page margin="20mm">
<x-slot:first-header>
<x-doc::text size="18pt" bold>Hartley & Finch</x-doc::text>
<x-doc::text size="9pt" color="slate-500">12 Mill Lane, Bristol</x-doc::text>
</x-slot:first-header>
<x-slot:header>
<x-doc::text size="8pt" color="slate-500">Hartley & Finch, continued</x-doc::text>
</x-slot:header>
…body…
</x-doc::page>use Quoin\{Column, Document, Page, Text};
use function Quoin\{mm, pt};
$body = [];
for ($i = 1; $i <= 60; $i++) {
$body[] = Text::make("Paragraph $i. " . str_repeat('Lorem ipsum dolor sit amet. ', 6));
}
$document = Document::make(
Page::a4()->margin(mm(20))
->firstHeader(
Text::make('Hartley & Finch')->size(pt(18))->bold(),
Text::make('12 Mill Lane, Bristol')->size(pt(9))->color('slate-500'),
)
->header(Text::make('Hartley & Finch, continued')->size(pt(8))->color('slate-500'))
->body(Column::make(...$body)->gap(pt(6))),
);A cover page with no header or footer
An empty slot means there is nothing on that page. In PHP, call the method with no arguments.
<x-doc::page>
<x-slot:header>
<x-doc::text size="8pt">Annual report</x-doc::text>
</x-slot:header>
<x-slot:footer>
<x-doc::page-number align="right" size="8pt" />
</x-slot:footer>
<x-slot:first-header></x-slot:first-header>
<x-slot:first-footer></x-slot:first-footer>
…cover, then the report…
</x-doc::page>use Quoin\{Column, Document, Page, PageBreak, PageNumber, Row, Spacer, Text};
use function Quoin\{mm, pt};
$document = Document::make(
Page::a4()->margin(mm(20))
->header(Text::make('Annual report')->size(pt(8)))
->footer(Row::make(Spacer::flex(), PageNumber::make()->size(pt(8))))
->firstHeader()
->firstFooter()
->body(Column::make(
Text::h1('Annual report'),
PageBreak::make(),
Text::make('The report starts here.'),
)),
);A booklet with mirrored margins
With mirrored margins, the left margin is the inside of the page and the right margin is the outside. On even pages the two swap, so the inside margin always sits next to the binding. Put the page number on the outside edge by giving odd and even pages opposite alignments.
<x-doc::page size="a5" margin="18mm 12mm 18mm 20mm" mirror>
<x-slot:footer>
<x-doc::page-number align="right" size="8pt" />
</x-slot:footer>
<x-slot:even-footer>
<x-doc::page-number align="left" size="8pt" />
</x-slot:even-footer>
…body…
</x-doc::page>use Quoin\{Column, Document, Page, PageNumber, Row, Spacer, Text};
use function Quoin\{mm, pt};
$body = [];
for ($i = 1; $i <= 60; $i++) {
$body[] = Text::make("Paragraph $i. " . str_repeat('Lorem ipsum dolor sit amet. ', 6));
}
$document = Document::make(
Page::a5()->margin(mm(18), mm(12), mm(18), mm(20))
->mirrorMargins()
->footer(Row::make(Spacer::flex(), PageNumber::make()->size(pt(8))))
->evenFooter(PageNumber::make()->size(pt(8)))
->body(Column::make(...$body)->gap(pt(6))),
);mirrorMargins(false) turns it off again.
Which one a page uses
Each page picks its header and its footer separately, in this order:
- The first page of the page run uses the first-page version, if there is one.
- Otherwise an even page uses the even-page version, if there is one.
- Otherwise the page uses the normal header or footer.
Each page run (each <x-doc::page>) has its own set. Page numbers count across the whole document, so the first page of a second run can still be an even page, and {page} shows its place in the document.
When a first page has a tall header, the body has less room on it. A block that can't split and doesn't fit the short first page moves to page 2.
In Word and HTML
Word export checks the matching boxes in the page setup: "Different First Page" for first-page versions, "Different Odd & Even Pages" for even-page versions, and "Mirror margins" for mirrored margins. Different First Page is set per page run. The other two apply to the whole document. Runs without even-page versions repeat their normal header and footer on even pages, so they look the same. Mixing a mirrored run with a run that isn't, when that run's left and right margins differ, is reported as approximated. In Word, a first-page header or footer you don't set shows the normal one, even when that page falls on an even page.
HTML export shows the first-page header at the top of the page (or nothing, if you set it empty) and the normal footer at the bottom. If the page has a first-page footer but no normal footer, the first-page footer is shown. If it has both, the normal one is shown and the export reports the first-page footer as approximated. Even-page versions aren't shown, and the export reports that as approximated. Mirrored margins apply only when the page is printed, and only from the first page run. The fragment output, the one you embed in another view, doesn't mirror.
Filling in an existing PDF
When the design already exists as a PDF, such as a certificate or a letterhead made in a design tool, a page template draws a page of it behind your page, at the same size. The overlay places your content at exact points on top.
<x-doc::page template="certificates/completion.pdf">
<x-slot:overlay>
<x-doc::place x="50%" y="42%" anchor="top">
<x-doc::text size="32pt" bold>{{ $learner->name }}</x-doc::text>
</x-doc::place>
<x-doc::place x="50%" y="55%" anchor="top">
<x-doc::text size="14pt">Completed {{ $course->title }} on {{ $completedOn }}</x-doc::text>
</x-doc::place>
<x-doc::place x="85%" y="80%" anchor="center" width="12%">
<x-doc::qr-code :value="$verifyUrl" width="100%" />
</x-doc::place>
</x-slot:overlay>
</x-doc::page>use Quoin\{Document, Page, PdfPage, Place, QrCode, Text};
use Quoin\Style\Anchor;
use function Quoin\{percent, pt};
$document = Document::make(
Page::template(PdfPage::file('/path/to/certificates/completion.pdf'))->overlay(
Place::at('50%', '42%', Text::make('Ada Lovelace')->size(pt(32))->bold())->anchor(Anchor::Top),
Place::at('50%', '55%', Text::make('Completed Analytical Engines on 21 October 2026')->size(pt(14)))->anchor(Anchor::Top),
Place::at('85%', '80%', QrCode::make('https://example.com/verify/123')->width(percent(100)))
->width('12%')->anchor(Anchor::Center),
),
);See the certificate example for a complete one, with a blank template, a name, a course, a date and a signature image.
The template
The page takes its size from the template page, so you can't set size or orientation alongside it. The template page is drawn as it is, never as a picture, so its text and artwork stay sharp at any zoom. Anything else you put on the page, including the background, is drawn over it.
In Blade, a relative template path stays inside quoin.image_path, the same as for images. If the PDF isn't a file on disk, for example when it's stored on S3, pass its bytes with :template-data="Storage::get($path)" instead. Use template-page="2" to draw a page other than the first, and template-password to open a password-protected template. In PHP, PdfPage::file($path, page: 2, password: '…') and PdfPage::bytes($bytes) take the same options.
Page::template() reads the PDF straight away to learn its size, so a missing file or a wrong password throws a PdfUnreadable exception there, before you render.
Placing content
Each place puts its content at a point given by x and y. These are measured from the top-left corner of the page, as lengths like 20mm or 0.8in, or as percentages of the page's width and height. Page margins don't apply to the overlay.
The anchor says which point of the content sits at that spot:
anchor | The point placed at x, y |
|---|---|
top-left (the default) | The top-left corner |
top, bottom | The middle of the top or bottom edge. top-center and bottom-center work too |
top-right, bottom-left, bottom-right | That corner |
left, right | The middle of the left or right edge. center-left and center-right work too |
center | The center |
In PHP, anchor() takes the Anchor case or its string, such as ->anchor('top'). Anchor::TopCenter, Anchor::BottomCenter, Anchor::CenterLeft and Anchor::CenterRight are the same cases under their other names.
With anchor="top", x is the middle of the content, so a short name and a long one both stay centered on the same point.
Without a width, a place is as wide as its content needs, up to the width of the page, and longer text wraps at the page edge. With a width, either a length or a percentage of the page width, the content is laid out in that width, and percentages inside the place are of the place's width. That's how the QR code above fills a box 12% of the page wide.
The overlay is drawn on top of everything else on the page and is repeated on every page the page template makes, so you can also use it for a stamp or a page number in a fixed spot. A <x-doc::place> only works in the overlay slot, and the overlay slot only takes <x-doc::place> tags.
Tips
Blade needs a space or a line break after a closing slot tag. If you write </x-slot:overlay>Body on one line, Blade reads it as an unknown @endslotBody directive and the slot is never closed.
Pages of a PDF inside your content
A page of a PDF can also go anywhere in your content, like an image, with <x-doc::pdf-page src="form.pdf" width="60mm" /> or PdfPage::file('form.pdf')->width(mm(60)). It's sized like an image too: from the page's own size, and setting one side keeps its proportions.
In HTML and Word exports
A browser can't draw a page of a PDF inline, so HTML exports leave templates and PDF pages out and report each one as dropped. Places are positioned over the page with CSS, which is close to the PDF but not exact.
Word export leaves templates and PDF pages out too. In an overlay place, only a lone image, QR code or SVG survives, as a floating picture; everything else is reported as dropped.
Controlling page breaks
By default content splits wherever it needs to. These options control where the breaks fall:
| PHP | Blade | What it does |
|---|---|---|
keepTogether() | keep-together | Moves the whole block to the next page instead of splitting it. A block taller than a page will still split. |
keepWithNext() | keep-with-next | Keeps the block on the same page as the one after it. Headings do this by default; turn it off with keepWithNext(false) or :keep-with-next="false". |
minLines(3) | min-lines="3" | Leaves at least this many lines of a paragraph on each side of a break. |
breakBefore(), breakAfter() | break-before, break-after | Starts a new page before or after the block. |
PageBreak::make() | <x-doc::page-break /> | Starts a new page at this point. |
use Quoin\{Column, Document, Page, PageBreak, Text};
use function Quoin\{in, pt};
$document = Document::make(
Page::letter()->margin(in(0.75))->body(
Column::make(
Text::h2('Section one'),
Text::make(str_repeat('Body text. ', 200))->minLines(3),
PageBreak::make(),
Text::h2('Section two'),
Column::make(Text::make('A block'), Text::make('that stays whole'))->keepTogether(),
)->gap(pt(8)),
),
);Bookmarks
The bookmarks panel that PDF viewers show beside the page is filled in. Every heading from h1 to h4 becomes a bookmark, nested by level, that jumps to that heading.
To bookmark something that isn't a heading, or to change a heading's entry, set bookmark:
<x-doc::h1>Annual report</x-doc::h1>
<x-doc::h2 bookmark="Summary">A long heading that reads badly in a sidebar</x-doc::h2>
<x-doc::h2 :bookmark="false">Left out of the panel</x-doc::h2>
<x-doc::card title="Terms" bookmark="Terms and conditions">…</x-doc::card>use Quoin\{Column, Document, Page, Text};
use Quoin\Decorator\Card;
$document = Document::make(Page::letter()->body(Column::make(
Text::h1('Annual report'),
Text::h2('A long heading that reads badly in a sidebar')->bookmark('Summary'),
Text::h2('Left out of the panel')->bookmark(false),
Card::make(Text::make('…'))->title('Terms')->bookmark('Terms and conditions'),
)));Bookmarks you add are top-level unless you give them a level, with bookmark-level="2" in Blade or ->bookmark('Terms', 2) in PHP. If a level skips one, like an h3 straight after an h1, it's nested one step down instead of leaving a gap. Headings in headers, footers and backgrounds are ignored, since they repeat on every page.
To leave the panel empty, pass bookmarks: false to PdfOptions, or set 'bookmarks' => false in the Laravel config. This only affects PDFs; HTML exports have no bookmarks panel.
Tables of contents
A table of contents lists your headings with the page each one lands on. Put it anywhere in a page body, before or after the headings it lists:
<x-doc::h1 toc="false">Handbook</x-doc::h1>
<x-doc::toc title="Contents" levels="1-3" />
<x-doc::page-break />
<x-doc::h1>Getting started</x-doc::h1>
<x-doc::h2>Installing</x-doc::h2>
<x-doc::h2 toc="false">Not listed</x-doc::h2>use Quoin\{Column, Document, Page, PageBreak, Text, Toc};
$document = Document::make(Page::letter()->body(Column::make(
Text::h1('Handbook')->toc(false),
Toc::make()->title('Contents')->levels(1, 3),
PageBreak::make(),
Text::h1('Getting started'),
Text::h2('Installing'),
Text::h2('Not listed')->toc(false),
)));Each entry is a heading's text, dot leaders, and its page number, right-aligned. A long title wraps, and the number sits on its last line. In the PDF every entry is a link to its heading. Page numbers are physical pages, the same as {page}, so a cover page is page 1.
The options:
levelspicks which heading levels to list, from 1 to 4. The default is 1 to 2. In Blade,levels="2"is level 2 alone andlevels="1-3"is a range. In PHP, it's->levels(1, 3).titleadds a line above the list. There is no default title. It isn't a heading, so it gets no bookmark and no entry.leadersturns the dot leaders off with:leaders="false"(orleaders="false") in Blade and->leaders(false)in PHP.
The entries are the h1 to h4 headings in page bodies, in document order, including headings from rich text, section and card titles given a heading level, and text made a heading with asHeading(). A document can have more than one table of contents, and each one is independent. Headings in headers, footers, backgrounds and overlays are never listed, and a table of contents there throws InvalidStructure. If no heading matches, the table of contents draws only its title and reports a warning.
To leave a heading out, use toc="false" in Blade or ->toc(false) in PHP. It keeps its bookmark. Setting bookmark="Short title" also sets the entry's text. bookmark(false) turns off the bookmark only, so the entry still shows the heading's own text. A level from bookmark($title, $level) is the entry's level too. To leave out every heading in converted HTML, use the markup tag's toc option.
The table of contents is an ordinary block. Entries never split across pages, and it doesn't start a new page by itself. Add a page break after it, as above, to start your content on a fresh page. The PdfOptions setting that turns bookmarks off doesn't affect it.
Its look comes from named styles you can change like any other (see Styles and themes):
| Style | Default |
|---|---|
toc | The whole block, with a 12pt bottom margin. |
toc.title | 14pt, bold, 8pt bottom margin. |
toc.entry | Every entry, 3pt bottom margin. |
toc.level-1 | Bold, 6pt above. |
toc.level-2, toc.level-3, toc.level-4 | Indented 12pt, 24pt and 36pt. |
The table of contents also takes the normal style attributes, such as margin or color. It takes no content inside the tag.
In Word it is a real table of contents field, and in HTML it is a list of links.
Content that doesn't fit
Sometimes something can't fit even on a fresh, empty page, such as an image with a fixed height taller than the page, or a table whose fixed column widths are wider than its box (Tables wider than their box). The same goes for a box with a height or max-height whose content needs more room, such as a long address in a label of fixed size. By default a LayoutOverflow exception is thrown that names the component, so you find out straight away.
To get the rest of the document instead, clip the oversized content and log a warning. A box with a height keeps its size and hides what doesn't fit, so nothing draws over the content below it:
use Quoin\OverflowMode;
use Quoin\Export\PdfOptions;
$options = new PdfOptions(overflow: OverflowMode::Clip, onWarning: fn (string $message) => error_log($message));In Laravel, set overflow in the config to 'throw' or 'clip'. The default, null, throws in the local and testing environments and clips everywhere else, so you see problems during development without breaking documents in production.