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[].span follows the same 12-grid rules as row/col.
  • colspan lets a single cell span multiple columns inside a row.
  • header, rows, and footer are all optional.
  • style.rowHeight is 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 %, no auto. Pick pt, mm, cm, or in.
  • Numbers don't auto-format. {{.total}} prints whatever number you sent. Use printf filters 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

Something unclear or missing on this page?