Element reference
Every element and attribute xml2pdf understands. Unknown elements and attributes are errors, so a typo is never silently ignored.
Any attribute value can contain ${variables}, and most elements also accept the style attributes (font, size, color, align, …). Lengths are in points unless given a unit; see Units.
<document>
The root element. It must contain at least one <page>.
Children: <constants>, <resources>, <watermark>, <header> (at most one), <footer> (at most one), <page>, <for-each>.
| Attribute | Values | Default | Description |
|---|---|---|---|
title | text | – | PDF metadata title, shown in viewer title bars. |
author | text | – | PDF metadata author. |
subject | text | – | PDF metadata subject. |
keywords | text | – | PDF metadata keywords. |
page-size | A3 A4 A5 Letter Legal Tabloid or WxH | A4 | Default page size, e.g. 100mmx150mm. See Page setup. |
orientation | portrait landscape | portrait | Default orientation. |
margin | 1–4 lengths | 0.5in | Default page margins (top right bottom left). |
| Style attributes: the base style for the whole document. The defaults are Helvetica, 11pt, black, left-aligned, line-height 1.2. | |||
<document title="Invoice ${no}" author="Acme" page-size="A4" margin="20mm" font="helvetica" size="10">
...
</document><constants>
Declares named values that can be referenced as ${name}. It's allowed directly under <document>. Values from --data and --set override constants with the same name. See Variables.
<const>
| Attribute | Values | Default | Description |
|---|---|---|---|
name | identifier | required | Letters, digits, _, - and ., starting with a letter or _. Must be unique. |
value | text | element text | The value. If it's omitted, the element's text content is used instead, which suits long values. It may reference other variables. |
<constants>
<const name="company" value="Acme Corp"/>
<const name="disclaimer">All prices include VAT. ${company} reserves the right to change prices.</const>
</constants><resources>
Declares images and named styles that are referenced elsewhere by id. It's allowed directly under <document>. Resources can be used anywhere in the document, regardless of where they're declared.
<image> (resource)
| Attribute | Values | Default | Description |
|---|---|---|---|
id | name | required | The name used by <img ref> and <watermark image>. |
src | file path | required | A PNG, JPEG or GIF file. Relative paths resolve against the XML file's directory (or --base-dir). A missing file is an error. |
<style> (resource)
| Attribute | Values | Default | Description |
|---|---|---|---|
id | name | required | The name used in style="...". |
extends | style ids | – | One or more parent styles (space-separated) whose properties this style starts from. Cycles are errors. |
Any style attributes. A style may also use style="..." to include other styles. | |||
<resources>
<image id="logo" src="images/logo.png"/>
<style id="h1" size="20" bold="true" color="#1f4e9c" margin-bottom="8"/>
<style id="h2" extends="h1" size="14"/>
</resources><page>
A page of content. Each <page> starts a new physical page, and its content continues onto more pages as needed, all with the same settings. See Layout & pagination.
Children: blocks (<text>, <img>, <table>, <spacer>, <page-break>), <for-each>, and loose inline text, which becomes a paragraph.
| Attribute | Values | Default | Description |
|---|---|---|---|
page-size | as on <document> | document's | Page size for this page. |
orientation | portrait landscape | document's | Orientation for this page. |
margin | 1–4 lengths | document's | Margins for this page. |
header | true false | true | Show the document header. With false, the space is given to the content. |
footer | true false | true | Show the document footer. |
watermark | true false | true | Show watermarks. |
| Style attributes: inherited by all content on the page. | |||
<page header="false" align="center"> <!-- cover page -->
<spacer height="2in"/>
<text size="28" bold="true">Annual Report</text>
</page>
<page orientation="landscape">...</page><header> / <footer>
Content repeated at the top or bottom of pages, inside the margins. In their text, {page} and {pages} become the current page number and the total page count. See Headers & footers.
Children: the same as <page>. Absolutely positioned blocks inside them use page coordinates.
| Attribute | Values | Default | Description |
|---|---|---|---|
height | length | content height | Fixed band height. |
gap | length | 6 | Space between the band and the page content. |
pages | page selector | all | The pages to show the band on. Its space is reserved on every page either way. |
| Style attributes, inherited from the document style. | |||
<header pages="2-">
<table widths="1*,1*" border="0" padding="0" size="8" color="gray">
<row><cell>Quarterly report</cell><cell align="right">Q3 2026</cell></row>
</table>
</header>
<footer><text align="center" size="8">Page {page} of {pages}</text></footer><watermark>
Text or an image drawn across pages, rotated and semi-transparent. You can declare any number of them. It needs exactly one of text (or text content), image or src. See Watermarks.
| Attribute | Values | Default | Description |
|---|---|---|---|
text | text | – | Watermark text. It can also be given as the element's content, and may use {page} and {pages}. |
image | image id | – | An image resource. |
src | file path | – | An image file. |
opacity | 0–1 | 0.15 | Transparency. |
rotate | degrees | 45 | Counter-clockwise rotation around the center point. |
layer | front back | front | Draw over or beneath the page content. |
x, y | length or % | page center | Center point, measured from the page's top-left corner. |
width, height | length or % | 50% of page width | Image size. If only one is set, the aspect ratio is kept. |
pages | page selector | all | The pages to draw on. |
Style attributes for text watermarks. The defaults are size="60", bold="true" and a medium gray color. | |||
<watermark text="DRAFT" size="100" color="#1f4e9c" opacity="0.12"/>
<watermark image="logo" width="60%" opacity="0.06" rotate="30" layer="back" pages="2-"/><text>
A paragraph. Whitespace is collapsed, lines wrap to the available width, and long words break at character boundaries. <p> is an alias.
Children: text and inline tags only.
| Attribute | Values | Default | Description |
|---|---|---|---|
x, y | length or % | – | Absolute position of the paragraph's top-left corner. See absolute positioning. |
width | length or % | available width | Paragraph box width. In the flow it can only make the box narrower. |
Style attributes, including align (left, center, right, justify), line-height, margin-top and margin-bottom. | |||
<text style="body" align="justify" margin-bottom="8">
Payment is due within <b>30 days</b>. Questions? Email <u>billing@example.com</u>.
</text>Inline tags
These are allowed inside <text>, and anywhere loose inline text is allowed. They can be nested.
| Tag | Effect | Attributes |
|---|---|---|
<b>, <strong> | bold | style attributes |
<i>, <em> | italic | style attributes |
<u> | underline | style attributes |
<span> | no effect of its own | style attributes, e.g. <span color="red" size="14"> |
<br/> | line break | none |
<img>
An image. <image> is an alias when used inside a page. It needs either ref or src. Images are never stretched beyond the available width or the content height; they're scaled down to fit instead.
| Attribute | Values | Default | Description |
|---|---|---|---|
ref | image id | – | An image declared in <resources>. |
src | file path | – | An image file (PNG, JPEG, GIF), relative to the XML file. |
width | length or % | natural size | Display width. If only width or only height is set, the aspect ratio is kept. |
height | length or % | natural size | Display height (a percentage is of the content height). |
align | left center right | inherited | Horizontal placement within the available width. |
x, y | length or % | – | Absolute position of the top-left corner. |
margin-top, margin-bottom and the other style attributes. | |||
The natural size is the pixel size at 72 dpi, or at the DPI recorded in a PNG file.
<img ref="logo" width="45mm"/>
<img src="charts/q3.png" width="80%" align="center" margin-bottom="10"/><table>
A grid of rows and cells. It breaks across pages between rows, repeating header rows.
Children: <row> and <for-each> (generating rows).
| Attribute | Values | Default | Description |
|---|---|---|---|
widths | comma-separated list | equal columns | Column widths. N* takes a share of the space left after fixed columns (* = 1*), a length is fixed, and % is a percentage of the table width. Example: widths="30mm,2*,1*,15%". Without it, the column count comes from the widest row. |
width | length or % | 100% | Table width. |
border | length | 0.5 | Cell border line width. 0 means no borders. |
border-color | color | black | Border color. |
padding | 1–4 lengths | 4 | Cell padding (top right bottom left). |
header-bg | color | – | Background of header rows. |
stripe | color | – | Background of every second body row. |
repeat-header | true false | true | Repeat header rows at the top of each continuation page. |
x, y | length or % | – | Absolute position (the table then doesn't paginate). |
| Style attributes, inherited by all cells. | |||
<table widths="4*,1*,1.5*" border="0.5" border-color="#bbb" padding="5 6"
header-bg="#1f4e9c" stripe="#f2f5fa" size="10">
<row header="true" color="white">
<cell>Description</cell><cell align="right">Qty</cell><cell align="right">Amount</cell>
</row>
<row><cell>Consulting</cell><cell align="right">12</cell><cell align="right">$1,800.00</cell></row>
<row bold="true"><cell colspan="2" align="right">Total</cell><cell align="right">$1,800.00</cell></row>
</table><row>
Children: <cell> and <for-each>. A row with fewer cells than columns is padded with empty cells; a row with more is an error.
| Attribute | Values | Default | Description |
|---|---|---|---|
header | true false | false | A header row: bold by default, uses header-bg, is kept with the next row, and repeats after page breaks. |
height | length | content | Minimum row height. |
bg | color | – | Row background, overriding header-bg and stripe. |
| Style attributes, inherited by the row's cells. | |||
<cell>
Children: inline text, or blocks (<text>, <img>, nested <table>, <spacer>), and <for-each>. Blocks inside cells can't use x/y.
| Attribute | Values | Default | Description |
|---|---|---|---|
colspan | number ≥ 1 | 1 | Number of columns this cell spans. |
valign | top middle bottom | top | Vertical alignment within the row. |
bg | color | – | Cell background, overriding the row's. |
Style attributes, e.g. align="right" for numbers. | |||
<cell valign="middle">
<text bold="true">Globex Ltd.</text>
<text size="8" color="gray">Customer since 2019</text>
</cell><spacer>
Vertical empty space. It's dropped if it would land at the top of a continuation page.
| Attribute | Values | Default | Description |
|---|---|---|---|
height | length | required | Amount of space. |
<spacer height="10mm"/><page-break>
Forces the following content onto a new page. It has no attributes. A break on a page that has no content yet does nothing, so it never produces blank pages.
<text style="h1">Chapter 1</text> ...
<page-break/>
<text style="h1">Chapter 2</text> ...<for-each>
Repeats its content once per element of an array. It can appear anywhere: as a child of <document> (to generate pages), <page>, <table> (rows), <row> (cells), <cell>, <text> (inline content), or another loop. See Loops.
| Attribute | Values | Default | Description |
|---|---|---|---|
items | variable path | required | The array to iterate: items, ${items}, order.lines or ${order.lines}. It must be an array, either from the JSON data or a Go slice. |
var | name | item | Variable holding the current element: ${item} or ${item.field}. |
index | name | – | Variable holding the 0-based position. |
number | name | – | Variable holding the 1-based position. |
<for-each items="${items}" var="item" number="n">
<row><cell>${n}</cell><cell>${item.name}</cell><cell align="right">${item.price}</cell></row>
</for-each>Style attributes
These styling attributes are accepted on <document>, <page>, <header>, <footer>, <watermark>, all blocks, table rows and cells, inline tags, and <style> resources. See Styles for how they cascade.
| Attribute | Values | Inherited | Description |
|---|---|---|---|
style | style ids | – | Named styles to apply, space-separated, left to right. The element's own attributes win. |
font | helvetica times courier zapfdingbats | yes | Font family. Aliases: arial/sans/sans-serif, serif/times-roman/times new roman, monospace/courier new. See Fonts. |
size | length | yes | Font size. font-size is an alias. |
bold | true false | yes | Bold weight. |
italic | true false | yes | Italic style. |
underline | true false | yes | Underline. |
color | color | yes | Text color. |
align | left center right justify | yes | Horizontal alignment of text and images. |
line-height | number | yes | Line height as a multiple of the font size (default 1.2). |
margin-top | length | no | Space above a block. |
margin-bottom | length | no | Space below a block. |
bg | color | no | Background color (table rows and cells). |
Booleans accept true/false, yes/no and 1/0.