Your first template
Walk through the JSON template grammar — pages, body, text, table, row/col, page-break — by way of building a real invoice.
Your first template
The shape of a render request is always the same:
{
"template": { ... },
"data": { ... },
"slug": "...",
"options": { ... }
}
Everything visual lives inside template. This guide builds up a one-page invoice piece by piece. By the end you'll have a feel for the four building blocks (text, spacer, row/col, table) that cover roughly 90% of all templates.
The shell
Every template starts with a page setup and a body:
{
"template": {
"page": { "size": "A4", "margin": "20mm" },
"body": []
}
}
| Field | Type | Notes |
|---|---|---|
page.size |
string | A4, A5, Letter, Legal, or [width, height] in pt. |
page.margin |
string | object | "20mm" (uniform), or { "top": "30mm", "bottom": "20mm", ... }. |
page.orientation |
string | portrait (default) or landscape. |
There's also header and footer — see Multi-page & page breaks.
Adding text
The simplest body node is text:
{
"body": [
{ "text": "Invoice #INV-001" }
]
}
You can attach a style:
{ "text": "Invoice #INV-001",
"style": {
"fontSize": 18,
"weight": "bold",
"color": "#111",
"align": "left",
"lineHeight": 1.4,
"letterSpacing": 0
}
}
| Property | Type | Default | Notes |
|---|---|---|---|
fontSize |
number | 11 | Points. |
weight |
regular | bold |
regular | |
style |
regular | italic |
regular | |
color |
hex string | #000 |
#rgb, #rrggbb, #rrggbbaa. |
align |
left | center | right | justify |
left | |
lineHeight |
number | 1.4 | Multiplier of fontSize. |
letterSpacing |
number | 0 | Extra space between glyphs in pt. |
Style keys can also be set via the inline shorthand "text|bold:Invoice" — but the explicit form is clearer and what we use throughout the docs.
Mixing data in
Anywhere a text value appears you can use Go-template syntax:
{ "text": "Invoice #{{.id}} — {{.customer.name}}" }
The data key on the request supplies the variable bag:
{
"template": { ... },
"data": {
"id": "INV-001",
"customer": { "name": "Acme, Inc." }
}
}
Filters ({{.total | printf "%.2f"}}), conditionals ({{if .paid}}…{{end}}), and loops ({{range .items}}…{{end}}) all work — see Go template language.
Spacing
spacer inserts vertical space:
{ "spacer": "8mm" }
Accepts any unit: "8mm", "24pt", "0.5in", "1cm".
For horizontal alignment within a row, use row/col — see below.
Rows and columns
Layout is a 12-column Bootstrap-style grid. A row contains one or more cols whose span values must sum to ≤ 12:
{ "row": [
{ "col": { "span": 8, "body": [{ "text": "Acme, Inc." }] }},
{ "col": { "span": 4, "body": [{ "text": "{{.date}}", "style": { "align": "right" }}] }}
]}
| Property | Type | Notes |
|---|---|---|
span |
integer 1–12 | Required. Total per row ≤ 12. |
body |
array | Same shape as the top-level body. Nest freely. |
align |
left | center | right |
Horizontal alignment of inner content. |
gap |
string | Horizontal space between adjacent cols. |
padding |
string | Internal padding of this column. |
Spans below 12 leave the rest of the row empty (useful for indentation). [1, 11], [3, 6, 3], [12] are all valid.
Tables
For tabular data, table is shorter than building it row-by-row:
{
"table": {
"columns": [
{ "span": 7 },
{ "span": 2, "align": "right" },
{ "span": 3, "align": "right" }
],
"header": [
[{ "text": "Description" }, { "text": "Qty" }, { "text": "Amount" }]
],
"rows": [
[{ "text": "Consulting" }, { "text": "12" }, { "text": "$2,400.00" }],
[{ "text": "Travel" }, { "text": "1" }, { "text": "$320.00" }]
],
"footer": [
[{ "text": "Total", "style": { "weight": "bold" }, "colspan": 2 },
{ "text": "$2,720.00", "style": { "weight": "bold" }}]
],
"style": {
"rowHeight": "11mm",
"headerFill": "#f3f4f6",
"borderColor": "#e5e7eb"
}
}
}
Notable bits:
columns[].spanfollows the same 12-grid rules asrow/col.colspanlets a single cell span multiple columns inside a row.header,rows, andfooterare all optional.style.rowHeightis the minimum — the engine will grow the row to fit wrapped text.
For dynamic rows from data, use a Go-template range:
{
"table": {
"columns": [{ "span": 8 }, { "span": 4, "align": "right" }],
"rows": "{{range .items}}[{\"text\":\"{{.name}}\"},{\"text\":\"{{.amount}}\"}]{{end}}"
}
}
The string-form rows is parsed once after templating; escaping JSON inside JSON is annoying, so most teams build the array on their side and pass it as data.items directly:
{
"table": {
"columns": [{ "span": 8 }, { "span": 4, "align": "right" }],
"rows": "{{ tableRows .items \"name,amount\" }}"
}
}
tableRows is a built-in helper documented in Document schema.
Putting it together
A complete invoice with header, body, and total:
{
"slug": "invoice_q1",
"template": {
"page": { "size": "A4", "margin": "20mm" },
"header": [
{ "row": [
{ "col": { "span": 6, "body": [
{ "text": "Acme, Inc.", "style": { "fontSize": 14, "weight": "bold" }},
{ "text": "12 Plaza St., NY 10003" }
]}},
{ "col": { "span": 6, "align": "right", "body": [
{ "text": "Invoice", "style": { "fontSize": 22, "weight": "bold", "color": "#0090a8" }},
{ "text": "Issued {{.date}}" }
]}}
]}
],
"body": [
{ "spacer": "12mm" },
{ "text": "Bill to" },
{ "text": "{{.customer.name}}", "style": { "weight": "bold" }},
{ "text": "{{.customer.address}}", "style": { "color": "#555" }},
{ "spacer": "10mm" },
{ "table": {
"columns": [
{ "span": 7 },
{ "span": 2, "align": "right" },
{ "span": 3, "align": "right" }
],
"header": [
[{ "text": "Description" }, { "text": "Qty" }, { "text": "Amount" }]
],
"rows": "{{ tableRows .items \"name,qty,amount\" }}",
"footer": [
[{ "text": "Total", "style": { "weight": "bold" }, "colspan": 2 },
{ "text": "{{.total | printf \"$%,.2f\"}}", "style": { "weight": "bold" }}]
]
}},
{ "spacer": "16mm" },
{ "text": "Thank you for your business." }
],
"footer": [
{ "text": "Page {{.page}} of {{.pages}}", "style": { "align": "center", "color": "#999" }}
]
},
"data": {
"date": "2026-04-14",
"customer": { "name": "Globex Corp.", "address": "1 Coyote Way, Albuquerque NM" },
"items": [
{ "name": "Consulting", "qty": 12, "amount": 2400 },
{ "name": "Travel", "qty": 1, "amount": 320 }
],
"total": 2720
}
}
That's a working production-grade invoice in roughly 30 lines.
A few things to keep in mind
- No CSS cascade. Styles live on the node they apply to; there's no inheritance. If you find yourself repeating styles, extract a snippet on your side and template it in.
- Exact units only. No
em, no%, noauto. Pickpt,mm,cm, orin. - Numbers don't auto-format.
{{.total}}prints whatever number you sent. Useprintffilters for currency, dates, percentages. - Big tables paginate automatically. A 5,000-row table rendered onto an A4 page will spread across however many pages it needs. Header + footer rows reflow.
What's next
- Document schema → — every node and field, in one table.
- CJK & fonts → — Japanese, Chinese, Korean, custom fonts.
- Multi-page & page breaks → — explicit breaks, repeating headers.
- Images, QR & barcode → — embeds and code generation.
Something unclear or missing on this page?