Decorators
Decorators are ready-made components for what most documents need: a bordered card, a highlighted note, a numbered section, an answer box. They take their look from the theme, so they match across your documents and you restyle them in one place.
There are twelve of them:
| Decorator | PHP | Blade |
|---|---|---|
| Card | Card | <x-doc::card> |
| Callout | Callout | <x-doc::callout> |
| Blockquote | Blockquote | <x-doc::blockquote> |
| Section | Section | <x-doc::section> |
| Field | Field | <x-doc::field> |
| Choice list | ChoiceList | <x-doc::choices> |
| Key-value list | KeyValueList | <x-doc::key-value> |
| Badge | Badge | <x-doc::badge> |
| Stat | Stat | <x-doc::stat> |
| Totals | Totals | <x-doc::totals> |
| Signature | Signature | <x-doc::signature> |
| Code block | CodeBlock | <x-doc::pre language="…"> |
The PHP classes are in the Quoin\Decorator namespace. Each is built from ordinary boxes, text and tables, so it breaks across pages like anything else and looks the same in PDF and HTML. Style methods and attributes apply to the outer box, so Card::make(...)->padding(pt(12)) changes the padding for that one card only.
Card
A bordered box, with an optional title bar.
<x-doc::card title="Respondent">
<x-doc::text>Jane Smith</x-doc::text>
</x-doc::card>
<x-doc::card>
<x-slot:title><x-doc::text>Rich <b>title</b></x-doc::text></x-slot:title>
…
</x-doc::card>use Quoin\{Document, Page, Text};
use Quoin\Decorator\Card;
$document = Document::make(Page::a4()->body(
Card::make(Text::make('Jane Smith'))->title('Respondent'),
));The title can be a string or any component, and it always stays on the same page as the start of the body. To make it a heading, see Titles as headings.
Callout
A tinted box with a colored bar down the left side, for notes and warnings.
<x-doc::callout type="warning" title="Before you start">
Answers cannot be changed once submitted.
</x-doc::callout>use Quoin\{Document, Page};
use Quoin\Decorator\Callout;
$document = Document::make(Page::a4()->body(
Callout::make('Answers cannot be changed once submitted.')->tone('warning')->title('Before you start'),
));The tones are note (the default), tip, warning and danger. No label such as "Warning" is added, so the wording and any translation are yours. In HTML, a callout becomes an <aside>.
Blockquote
A quotation with a bar down the side and an optional attribution.
<x-doc::blockquote cite="Jane Smith, closing round">
I came for the PDFs and stayed for the pagination.
</x-doc::blockquote>use Quoin\{Document, Page};
use Quoin\Decorator\Blockquote;
$document = Document::make(Page::a4()->body(
Blockquote::make('I came for the PDFs and stayed for the pagination.')->cite('Jane Smith, closing round'),
));The citation appears below the quote, after an em dash. Long quotes can split across pages. For a short one, add keep-together so the quote and its citation stay on the same page.
Section
A heading with its content, an optional number, and an optional line under the heading.
<x-doc::section number="3" title="Search terms" rule keep-together>
…
</x-doc::section>
<x-doc::section number="3">
<x-slot:title><x-doc::markup :text="$prompt" /></x-slot:title>
…
</x-doc::section>use Quoin\{Document, Page, Text};
use Quoin\Decorator\Section;
$document = Document::make(Page::a4()->body(
Section::make(Text::p('Library catalog, then the open web.'))
->number('3')
->title('Search terms')
->rule()
->keepTogether(),
));The number is a string, so 3, 3.2 and C all work. Sections aren't counted for you and no punctuation is added, and the theme controls how the number looks. With keep-together, a section that fits on one page is never split. A longer one still breaks, but its heading always stays with the start of its content.
Titles as headings
A section or card title is plain text unless you give it a heading level. heading="1" to heading="4" (->heading(1) in PHP) makes the title a real heading: it gets a PDF bookmark, an entry in the table of contents, an h1 to h4 tag in HTML and a Heading 1 to 4 style in Word. It keeps the section's or card's own title look.
<x-doc::toc />
<x-doc::section number="1" title="Units" heading="1">
…
</x-doc::section>
<x-doc::card heading="2">
<x-slot:title>{{ $unit->name }}</x-slot:title>
…
</x-doc::card>use Quoin\{Document, Page, Text, Toc};
use Quoin\Decorator\{Card, Section};
$document = Document::make(Page::a4()->body(
Toc::make(),
Section::make(Text::p('Every unit in the course.'))->number('1')->title('Units')->heading(1),
Card::make(Text::p('Reading and discussion.'))->title('Unit 1: Foundations')->heading(2),
));A numbered section's entry and bookmark include the number, such as "1 Units". To set different text, put bookmark("…") on the title Text, or in Blade build the title in PHP. The title has to be text. A title slot is joined into one line of text, so a heading tag inside the slot doesn't make a heading; use heading instead. In PHP, a title that is a box or other component can't be a heading and throws InvalidStructure.
To make any text a heading without the h1 to h4 look, use Text::make('…')->asHeading(2).
Field
A bordered box showing an answer or value, with a placeholder when it's empty. For a paper-form look, variant="line" keeps only a rule along the bottom.
<x-doc::field label="Comments" placeholder="No response" lines="3">{{ $comments }}</x-doc::field>use Quoin\{Document, Page};
use Quoin\Decorator\Field;
$comments = '';
$document = Document::make(Page::a4()->body(
Field::make($comments)->label('Comments')->placeholder('No response')->lines(3),
));A field counts as empty if it has no content or only whitespace. lines sets a minimum height in lines of text, so the box scales with the theme's font size and line height. If those lines won't fit in the space left on the page, the field moves to the next page.
Without a label, style attributes apply to the box. With a label, they apply to the label and box together. To style only the box, use the theme's field style.
Choice list
A list of options with checkboxes or radio buttons, some of them checked.
<x-doc::choices type="checkbox" emphasize-selected>
<x-doc::choice selected>Library catalog</x-doc::choice>
<x-doc::choice selected>Web search</x-doc::choice>
<x-doc::choice>Asked a colleague</x-doc::choice>
</x-doc::choices>use Quoin\{Document, Page};
use Quoin\Decorator\ChoiceList;
$document = Document::make(Page::a4()->body(
ChoiceList::checkbox()
->option('Library catalog', selected: true)
->option('Web search', selected: true)
->option('Asked a colleague')
->emphasizeSelected(),
));type is checkbox (the default) or radio. In PHP, use ChoiceList::checkbox() or ChoiceList::radio(). emphasize-selected makes the selected labels bold.
The checkboxes and radio buttons are drawn as shapes, so they don't depend on your font having ☐ or ● characters, and they look the same in PDF and HTML. In Word they are written as the characters ☐, ▣, ○ and ◉, so they take the font's look there. They're sized to match the text and line up with the first line of each label. A long list can break across pages between options, but never in the middle of one.
Key-value list
Labels and values in two aligned columns.
<x-doc::key-value label-width="30%">
<x-doc::kv label="Respondent">Jane Smith</x-doc::kv>
<x-doc::kv label="Submitted">2026-03-02 14:30</x-doc::kv>
<x-doc::kv label="Overall"><x-doc::badge type="tip">Agree</x-doc::badge></x-doc::kv>
</x-doc::key-value>use Quoin\{Document, Page};
use Quoin\Decorator\{Badge, KeyValueList};
use function Quoin\percent;
$document = Document::make(Page::a4()->body(
KeyValueList::make()
->row('Respondent', 'Jane Smith')
->row('Submitted', '2026-03-02 14:30')
->row('Overall', Badge::make('Agree')->tone('tip'))
->labelWidth(percent(30)),
));It's a borderless table, so the labels line up and a long list breaks cleanly between rows. Without label-width, the label column is as wide as the longest label. For long labels, set a width so they wrap and leave room for the values.
Badge
A small rounded label, for statuses and tags.
<x-doc::badge type="warning">Overdue</x-doc::badge>use Quoin\{Document, Page};
use Quoin\Decorator\Badge;
$document = Document::make(Page::a4()->body(
Badge::make('Overdue')->tone('warning'),
));The tones are neutral (the default), note, tip, warning and danger, matching the callout colors. A badge is a block that's only as wide as its text. For a lighter look, variant="outline" draws a border in the tone's color instead of filling the badge.
Inline badges
To put a badge in the middle of a line of text, use it inside a text tag. In Blade, <x-doc::badge> inside a text tag (<x-doc::text>, <x-doc::p>, a heading <x-doc::h1> to <x-doc::h4>, or the value of a stat) is an inline badge, and anywhere else it is the block badge above. A list item or table cell holds blocks, so a badge tag there is a block badge: write it as markup in the cell's text (<badge type="tip">New</badge>) or wrap the line in <x-doc::p>. In inline markup it is <badge>, with the same type and variant attributes.
<x-doc::text>
The call returns <x-doc::badge type="tip">201</x-doc::badge> and the new record.
</x-doc::text>use Quoin\Text;
Text::markup('The call returns <badge type="tip">201</badge> and the new record.');use Quoin\{Span, Text};
Text::make('The call returns ')->append(Span::badge('201', 'tip'), ' and the new record.');The label is plain text: a tag inside <badge> is an error, and so is an empty label. A badge inside <a> is part of the link. The PDF draws a rounded pill on the line and doesn't split it across lines unless it is wider than the line; one that doesn't fit moves whole to the next line. HTML export writes <span class="pc-badge">. Inline badges use the same theme styles as block badges (badge, badge.<tone>, badge.<variant>). In Word the badge is shaded text with a little padding, without rounded corners, and Google Docs shows the shading only. A block badge with a plain-text label is written the same way in Word.
Stat
A figure on a tinted panel: a small label, the value in large type, and an optional note under it. Put several in a row for a summary strip.
<x-doc::row gap="12pt">
<x-doc::stat label="Revenue" note="Up 12% on Q2" grow="1">$48,200</x-doc::stat>
<x-doc::stat label="Orders" note="38 refunded" grow="1">1,204</x-doc::stat>
<x-doc::stat label="Rating" grow="1">4.7</x-doc::stat>
</x-doc::row>use Quoin\{Document, Page, Row};
use Quoin\Decorator\Stat;
use function Quoin\pt;
$document = Document::make(Page::a4()->body(
Row::make(
Stat::make('$48,200')->label('Revenue')->note('Up 12% on Q2')->grow(1),
Stat::make('1,204')->label('Orders')->note('38 refunded')->grow(1),
Stat::make('4.7')->label('Rating')->grow(1),
)->gap(pt(12)),
));The value is the tag's content, and it takes inline tags, so <span color="emerald-600">+4.2%</span> colors it. label and note also work as slots. On its own a stat spans the width like any box. In a row each one is as wide as its content, so give each grow="1" to share the width evenly.
Totals
The rows under an invoice or quote: labels on the left, amounts right-aligned, and the total in bold above a rule.
<x-doc::totals>
<x-doc::kv label="Subtotal">$1,000.00</x-doc::kv>
<x-doc::kv label="Tax (8.25%)">$82.50</x-doc::kv>
<x-doc::kv label="Total due" total>$1,082.50</x-doc::kv>
</x-doc::totals>use Quoin\{Document, Page};
use Quoin\Decorator\Totals;
$document = Document::make(Page::a4()->body(
Totals::make()
->row('Subtotal', '$1,000.00')
->row('Tax (8.25%)', '$82.50')
->total('Total due', '$1,082.50'),
));The rows are the same <x-doc::kv> tags as a key-value list, and total marks the ones to emphasize. Any row can be a total, so a total followed by "Amount paid" and a second total for the balance works too. The block is 45% of the width and sits at the right; change that with width, for example width="2.75in" or width="100%". Next to a paragraph with grow="1" in a row, such as payment notes, the totals keep their width and the paragraph takes the rest.
Signature
A line to sign on, with the signer's name, role and date under it.
<x-doc::row gap="36pt">
<x-doc::signature name="Jane Smith" role="Director" date="12 March 2026">
<x-doc::svg src="signature.svg" height="28pt" />
</x-doc::signature>
<x-doc::signature name="Witness" role="Name and date" />
</x-doc::row>use Quoin\{Document, Page, Row};
use Quoin\Decorator\Signature;
use function Quoin\pt;
$document = Document::make(Page::a4()->body(
Row::make(
Signature::make()->name('Jane Smith')->role('Director')->date('12 March 2026'),
Signature::make()->name('Witness')->role('Name and date'),
)->gap(pt(36)),
));Whatever the tag holds sits on the line: a signature image, a typed name, or nothing, which leaves room to sign by hand. name, role and date are each optional and also work as slots. The date isn't formatted, so pass it the way the document needs it. A signature is 3 inches wide and never splits across pages.
Restyling
Each decorator gets its look from named styles in the theme, such as card, card.title and callout.warning. Define a style with the same name to replace the built-in one.
// config/quoin.php
'styles' => [
'callout.warning' => ['border-color' => 'orange-500', 'background' => 'orange-50'],
],use Quoin\{Document, Page};
use Quoin\Decorator\Callout;
use Quoin\Export\PdfOptions;
use Quoin\Style\{Style, Theme};
use Quoin\Value\Color;
$theme = Theme::default()->withStyle('callout.warning', Style::make(
borderColor: Color::parse('orange-500'),
background: Color::parse('orange-50'),
));
$document = Document::make(Page::a4()->body(Callout::make('Mind the gap.')->tone('warning')));
$options = new PdfOptions(theme: $theme);
// $document->toPdf($options)->save('out.pdf');Nothing is merged: your style replaces the built-in one entirely, so include every property you want to keep. The decorator styles reference lists every name and its defaults.
Adding a tone
To add a tone, define its styles and use its name:
'styles' => [
'callout.success' => ['border-color' => 'green-600', 'background' => 'green-50'],
'callout.title.success' => ['color' => 'green-800'],
'badge.success' => ['background' => 'green-100', 'color' => 'green-800'],
],<x-doc::callout type="success" title="Submitted">Thank you.</x-doc::callout>
<x-doc::badge type="success">Passed</x-doc::badge>Variants
A variant restyles every part of a decorator at once. variant="compact" makes the decorator also apply <name>.compact after each of its built-in names, whenever your theme defines that name. Define only the parts the variant changes:
'styles' => [
'callout.compact' => ['padding' => '4pt 8pt', 'gap' => '2pt'],
'callout.title.compact' => ['font-size' => '0.9em'],
],<x-doc::callout type="tip" title="Shortcut" variant="compact">...</x-doc::callout>use Quoin\Decorator\Callout;
Callout::make('...')->tone('tip')->title('Shortcut')->variant('compact');Several variants can be given, separated by spaces (variant="flat compact"), and apply in that order. A variant is a lowercase word of letters, digits and hyphens, and it cannot be a word that appears in one of the decorator's own part names (selected or radio on choices, title on a card), because the name it produces would be an existing part's. Such a word is rejected with an error naming the collision. callout and badge also reject their own tone words (note, tip, warning, danger, and neutral on a badge) as variants. Use tone() for those. Variants come after the tone (callout.title.warning, then callout.title.compact) and before your own style="" and style modifiers, which still win on the outer box.
In Blade, a variant for which the theme has no style on any part of that decorator throws an error listing the names it looked for. In PHP, a variant nothing styles does nothing, because the decorator has no theme to check against.
A few variants are built in, and your theme can restyle them like any other name:
| Variant | Look |
|---|---|
<x-doc::field variant="line"> | A form line: only a rule along the bottom, no box. |
<x-doc::badge variant="outline"> | A border in the tone's color, with no fill. |
<x-doc::card variant="flat"> | A tinted panel with no border. |
<x-doc::section variant="large"> | A bigger number and title, with more room around them. |
The code block also has strip and caption built in.
Your own decorator
A decorator is a class that implements Quoin\Decorator\Decorator. The interface needs render(), the style methods, variant(), variants() and partNames(). use HasStyle covers the style methods, and use HasVariants covers variant() and variants(). You write partNames() (every built-in style name the decorator applies, without tones) and render(). Build each name with the part() helper, so variants work, and apply the user's own style last:
use Quoin\{Node, Text, View};
use Quoin\Concerns\{HasStyle, HasVariants};
use Quoin\Decorator\Decorator;
final class Stamp implements Decorator
{
use HasStyle;
use HasVariants;
private function __construct(private string $label)
{
}
public static function make(string $label): self
{
return new self($label);
}
public function partNames(): array
{
return ['stamp'];
}
public function render(): Node
{
return View::make(Text::make($this->label))
->apply(trim($this->part('stamp') . ' ' . ($this->styleName() ?? '')))
->apply($this->style());
}
}The theme has no stamp style, so the export throws until you add one to your theme's styles. The built-in decorators are final, immutable builders. Follow the same pattern: return clones from your setters.
A full example
The responses example uses eight of the decorators to lay out a completed feedback form, in Blade and PHP.