Skip to content
LpdfDocsv0.36-r1119.4

Lpdf is pre-release. The XML schema and SDK APIs can change between releases.

All Elements

Complete attribute reference for every lpdf XML element. Use Ctrl+F to find the element you need.

Lengths, tokens and colors are described in XML Schema.

Root element.

Attribute Type Required Description
version integer yes Schema version — always 1

Container for font, image and color profile declarations. Comes before tokens and document.

Attribute Type Description
name string Required. Alias used in the document. Lowercase letters, digits and -, starting with a letter
core string Built-in PDF font: Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Symbol, ZapfDingbats
src path Path of a .ttf or .otf file, read by the SDK from the machine that renders
ref string The key the font’s bytes are registered under with loadFont. Defaults to name

A built-in font can also be used by its name without declaring it: font="Courier".

Attribute Type Description
name string Required. Alias used in img elements. Same characters as a font name
src path Path of the image file (JPEG, PNG, WebP, GIF, TIFF, BMP or SVG: see Formats), read by the SDK from the machine that renders. URLs and data URIs are not fetched
ref string The key the image’s bytes are registered under with loadImage. Defaults to name

An image needs either a readable src or bytes loaded with loadImage.

An ICC color profile: the profile of the printing press a PDF/X document is made for, which the printer gives out. profile on output names it.

Attribute Type Description
name string Required. Alias the profile of output uses. Same characters as a font name
src path Path of the .icc file, read by the SDK from the machine that renders
ref string The key the profile’s bytes are registered under with loadProfile. Defaults to name

It has to be a printer profile, in gray, RGB or CMYK. The engine bundles no press profile.

Container for custom scales, colors and spot colors, placed before document. See Tokens.

Child Description
space, text-size, border, radius, width, height, grid Replace one scale. Each takes all six of xs s m l xl xxl, as lengths in pt, mm or in. height is the row for the heights of boxes, tables, images, shapes and barcodes: xs 16pt, s 24pt, m 32pt, l 48pt, xl 64pt, xxl 96pt
line-height Replaces the line-height scale. It takes all six too, but as factors of the font size, not lengths: xs 1.0, s 1.1, m 1.2, l 1.4, xl 1.6, xxl 2.0
aliases Holds alias elements
colors Holds color elements
spots Holds spot elements
gradients Holds gradient elements
rulings Holds ruling elements

A name of your own for a slot of the scale. An attribute that takes a slot (xs to xxl) takes the name in its place, and reads the slot of its own row: with caption for xs, font-size="caption" is the text size xs and gap="caption" the space xs. See Aliases.

Attribute Type Description
name string Required. Lowercase letters, digits and -, starting with a letter. Not xs s m l xl xxl fill or full, which mean something already
value string Required. The slot the name stands for: xs s m l xl or xxl. Not another alias
Attribute Type Description
name string Required. Name to use in any color attribute. A color named text becomes the default text color
value color Required. #rgb, #rrggbb, cmyk(), rgb() or hsl(). See Colors

A spot color: an ink of its own, printed from a plate of its own, in spots inside tokens. A color attribute takes its name, solid, or a tint of it after a space: background="brand 30%". See Spot colors.

Attribute Type Default Description
name string — Required. The name a color attribute gives. Lowercase letters, digits and -, starting with a letter. Not a name of colors
ink string — Required. The ink’s name as the printer knows it, which names its plate, such as PANTONE 1665 C. Not All, None, Cyan, Magenta, Yellow or Black
value color — Required. The color that stands in for the ink on a screen or a proof: #rgb, #rrggbb, cmyk(), rgb() or hsl(), not a color name
overprint boolean false Whether the ink prints on top of the inks under it, as a varnish or a die line does

A named blend of colors, in gradients inside tokens. A background or a fill uses it as gradient:name, and the blend spans the box it fills. Give from and to for two colors, or stop children for more. See Gradients.

Attribute Type Default Description
name string — Required. The name that follows gradient:. Lowercase letters, digits and -, starting with a letter
type string — Required. linear or radial
from color — The first color: hex, cmyk(), rgb(), hsl(), a color name, or a spot color or a tint of it. Used with to, when there are no stop children. For a radial gradient it is the center
to color — The last color. Used with from. For a radial gradient it is the edge
angle number 0 The direction of a linear gradient, in degrees: 0 runs from the top to the bottom, 90 from the left to the right, 180 from the bottom to the top. A radial gradient has no direction

A color at a place along a gradient. A gradient takes two or more, in increasing order, in place of from and to.

Attribute Type Description
offset percent Required. Where the color is reached, from 0% (the start) to 100% (the end). Offsets must increase
color color Required. Hex, cmyk(), rgb(), hsl(), a color name, or a spot color or a tint of it. A gradient’s colors are never another gradient, and are all CMYK, all RGB, or all tints of one spot color

Lines on every page of a section that names it with ruling, in rulings inside tokens: ruled paper, squared paper, or a page cut into equal parts. It holds one or more lines. See Rulings.

Attribute Type Default Description
name string — Required. The name a section gives in ruling. Lowercase letters, digits and -, starting with a letter
origin string page The space the lines fill and a count divides: page, up to the trim edge, or margin, inside the margin of the section’s layout or markdown
edges boolean true Whether the lines on the edges of that space are drawn
ocg string — print or screen: the lines are only printed, or only shown on screen

One set of lines of a ruling, cut by a step or a count in each direction. A direction with neither has no lines, and a step and a count in the same direction is an error. A cell narrower than 2.5pt is an error.

Attribute Type Default Description
step length — The distance between two lines in both directions
step-x length — The distance between the lines that run down the page. Takes the place of step
step-y length — The distance between the lines that run across the page. Takes the place of step
count whole number — Equal parts in both directions, from 1 to 100
count-x whole number — Equal columns, from 1 to 100. Takes the place of count
count-y whole number — Equal rows, from 1 to 100. Takes the place of count
color color line-muted The color of the lines
thickness token/length 0.4pt A length or a name of the border row

Document properties written to the PDF. Child of document, before the sections.

Attribute Type Description
title string Document title
author string Author
subject string Subject
keywords string Keywords
creator string Creating application
lang string The language of the text, as a language tag such as en-US, which a screen reader reads it in. A PDF/UA document needs it, and a PDF/A document of level a takes it only as a language tag

How the PDF file is written, apart from what its pages show: whether it is encrypted, and what a reader may do with it, whether it is PDF/A, PDF/UA or PDF/X, whether it is linearized, and how strictly a Factur-X invoice keeps to its spec. Child of document, after meta and before the sections. The passwords are not here: they come with the render call.

Attribute Type Default Description
encrypt string — aes-256 rc4-128: encrypts the PDF with this cipher, with the passwords of the render call. Without it the PDF is not encrypted, and passwords given to the render are an error
allow list nothing What a reader may do without the owner password, separated by spaces: all, or any of print modify copy annotate fill-forms accessibility assemble. Without it, or with allow="", nothing is allowed. It needs encrypt
pdfa string — 2a 2b 2u 3a 3b 3u: writes the PDF as PDF/A-2a, PDF/A-2b, PDF/A-2u, PDF/A-3a, PDF/A-3b or PDF/A-3u. Level a tags the file as pdfua does, without PDF/UA’s checks. The render needs createdOn, every text a font of assets, and the document no CMYK color, form field, barcode digits, encrypt, or attachments in part 2, and at level a no lang that is not a language tag and no character of Unicode’s private use area, each an error that says what to change. With 3a, 3b or 3u, an attachment named factur-x.xml or xrechnung.xml makes the PDF a Factur-X e-invoice
pdfua string — 1: writes the PDF as PDF/UA-1, a tagged PDF a screen reader can read. It combines with pdfa, and with 2a or 3a the file is PDF/A level a too. The render needs createdOn, meta a title and a lang, every img and barcode of the layout outside a header or a footer an alt, and every text a font of assets, each an error that says what to change
pdfx string — 4: writes the PDF as PDF/X-4, for a commercial printer, made for the press profile profile names. It combines with pdfua. Every page gets a TrimBox and a BleedBox, RGB is tied to sRGB, and links print as text. The render needs createdOn, meta a title, and every text a font of assets, and the document no form field, barcode digits, encrypt, pdfa or attachments, each an error that says what to change
profile string — The profile of assets a PDF/X file is made for: the ICC profile of the printing press. It needs pdfx, and pdfx needs it
linearize boolean false Writes the PDF linearized, for fast web view: page 1 and hints that say where every other page is come first, so a viewer that fetches the file by ranges shows page 1 while the rest downloads. Each page then names only the fonts and images it draws. With encrypt the file is encrypted first and linearized last. Any change to the file afterwards ends the linearization
facturx-strict boolean false Refuses, in a Factur-X invoice, an invoice file whose mime is not text/xml or whose relationship its profile doesn’t allow, and another file with no mime or of a format the Factur-X spec doesn’t list. It does nothing in a document without factur-x.xml or xrechnung.xml

The files the PDF carries inside it, which a reader lists in its attachments panel: see Attachments. Child of document, after meta and output and before the sections. It holds one file for each file.

A file the PDF carries. Child of attachments. The SDK reads it from src, or it was loaded on the engine under its ref or name.

Attribute Type Default Description
name string required The name a reader shows the file under and saves it as. Each file of a document has a name of its own
src path — Where the SDK reads the file from, when it was not loaded on the engine
ref string the name The key the file was loaded on the engine under
mime string application/octet-stream The type of the file, such as text/xml or application/pdf. A Factur-X invoice file defaults to text/xml
relationship string unspecified source data alternative supplement unspecified: how the file relates to the document. A Factur-X invoice file defaults to the one its profile asks for
description string — A line about the file, which a reader shows beside its name
Attribute Type Default Description
size string a4 letter legal a3 a4 a5, or a custom "200pt 300pt" or "210mm 297mm", each size 3pt at least
orientation string portrait portrait landscape
bleed length — How far each page reaches past its trim edge, such as 3mm, for a background or an image that runs off the page when it is cut. The page grows by it, its background fills it, and the layout keeps to the trimmed page. See PDF/X
font string Helvetica Default font: a built-in name or an asset name
background color or gradient:name — Page background: a color, or a gradient that spans the page
footnote-counter string section Where the numbers of the footnotes start over: page, section or document. A section’s own value overrides it
debug boolean false Render layout boxes

A document holds an optional meta, an optional output, optional attachments and one or more section elements. Any other attribute is an error, width, height, color, title and font-size among them, and the one for margin says it is set on the layout. Set a page size with size="200pt 300pt", and the title on meta.

Attribute Type Default Description
size string inherit Override page size for this section, each size 3pt at least. With grow, the starting size
orientation string inherit Override orientation
bleed length inherit Override the bleed for this section’s pages; 0mm takes it away
background color or gradient:name inherit Section background. A gradient spans the page
ruling string — The name of a ruling of the tokens, whose lines are drawn on every page, under everything else and over the background
footnote-counter string inherit Where the numbers of the footnotes in this section start over: page, section or document. Overrides the document’s
title string — Section title. Accepted, but not used: the PDF’s outline takes its entries from bookmarks
type string — toc: the section is the document’s table of contents, laid out last with the data $toc. One per document
toc-indent-step token/length 12pt In a table of contents, the left padding an entry gets for each level below the first
page-start whole number — The number of the section’s first page, which starts a new run of pages: 1 restarts the count. 1 or more. Without it the pages count on from the section before. See Page numbers
page-format string the section before’s How the page numbers are written: decimal, lower-alpha, upper-alpha, lower-roman or upper-roman. Past z, letters repeat: aa, bb, cc
page-prefix string the section before’s Text before the page numbers, such as A-. "" takes it away
columns whole number 1 Sets the section’s flow, a layout or a markdown, in this many columns, from 1 to 12: each fills like a small page, left to right, then the next page. See Columns
column-gap token/length l The space between two columns, as gap takes it. Ignored with one column
column-rule border — A line in the middle of each gap between two columns that hold something, as border takes it: 0.5pt #cccccc. Ignored with one column
column-fill string auto How the columns of the last page fill: auto, in order like every other page, or balance, levelled. CSS’s default is balance. Ignored with one column
grow string — Lets the page grow to fit the content, where it would start a new page or squeeze it: width, height or width height. size is then the starting size. Up to 14,400pt (200in) in each size; an error with columns or an inset. See A page that grows
debug boolean false Render layout boxes

A section can start with one bookmark, which marks its first page, followed by layers and at most one layout or one markdown, painted in the order they are written. A layer before the layout is painted under it, and a layer after it is painted over it. A section with neither is one page.

The flowing content of a section. Its elements are layout elements.

Attribute Type Default Description
margin spacing 36pt The space between the page edges and the flowing content and its regions: 48pt, a token, or one to four values like "48pt 24pt". A layer ignores it

Markdown as the content of a section, in the place of a layout. It holds an optional markdown-styles and one markdown-content, and nothing else: the page, a header, a footer or a cover stay in the XML around it, and a layer draws a header or a footer in its margin. See Markdown.

Attribute Type Default Description
margin spacing 36pt The space between the page edges and the Markdown, as the margin of a layout
font string the document’s The font of the Markdown, which a rule can change
font-size token/length m The size of its text, which a rule can change
color color the text token The color of its text, which a rule can change
gap token/length l The space between blocks
bookmarks integer 6 How many levels of headings are bookmarks, 0 to 6
debug boolean false Draw the outline of each box

The rules that say how each part of a markdown looks, inside markdown. A rule is an element named after the Markdown it styles: h1 to h6, p, code, quote, li, a, strong, em, del, table, th and td. It takes the attributes of the Lpdf element it becomes, and an attribute it does not set stays as the file or the defaults have it. See Styling.

Attribute Type Default Description
src string — A file of rules, whose root is a markdown-styles. The rules written inside override it, and it overrides the defaults. The SDK, the command line or the extension reads it, as it reads the src of a font or an image

The Markdown, inside markdown: written inline, best in a CDATA section, with the indent its lines share removed first, or read from the data. See Where the Markdown comes from.

Attribute Type Default Description
data-value string — The path in the data of a string that holds the Markdown. The text written inside is what a document with no data shows

Layout elements live inside layout. Every one except region, span and bookmark takes data-source, data-if and data-if-not, and text and barcode take data-value. See Data Binding.

column, row, grid, frame and td take these, beside their own:

Attribute Type Default Description
gap token/length 0 Space between children. Not on frame, which has one child
padding spacing 0 Space inside the edge: 8pt, a token, or one to four values like "8pt 16pt"
width token/length/fill — Fixed width, or fill: the full width, and in a row the width the other children leave. Not on td: the table’s cols sets cell widths
height token/length/fill/full — A length fixes the height, as a length or a name from the height row of tokens; fill takes what is left after siblings; full takes all the height available. Any of them stops the box splitting across pages
paginate string — Page breaks: no break-before break-after keep-next. See Page breaks
background color or gradient:name — Background fill: a color, or a gradient that spans the box
border BorderValue — Border, written "thickness color"
radius token/length 0 Corner radius
color color inherit Color of the text inside. A text that sets none takes the nearest box’s, else the text color. See Text color in a box
opacity 0–1 1 How opaque the box and everything in it is, as one. See Opacity
shadow string — A hard-edged shadow under the box: "x y color", with an optional opacity after the color. See Shadow
font string inherit Font for the text inside
font-size token/length inherit Font size for the text inside
debug boolean false Draw the box outlines
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Vertical column of children.

Attribute Type Default Description
align string stretch Horizontal alignment: start center end stretch
justify string start Vertical distribution: start center end between
bulk boolean false true lays out the texts of its text with data-source a page at a time, straight from the data. See Bulk Records

Children side by side, continuing on the next line when they run out of width. A child with width="fill" takes the width its line leaves, shared equally when several on the line use it, and never moves to the next line.

Attribute Type Default Description
align string start Vertical alignment on each line: start center end. stretch acts as start
justify string start Distribution along each line: start center end between. between puts the first child at the left edge, the last at the right, and the others evenly between

Equal columns, filled left to right.

Attribute Type Default Description
cols integer 1 Number of columns (1–12)
col-width token/length — Minimum column width: fits as many columns as the width allows, at least one, stretched to fill the row (overrides cols). Tokens are grid sizes
bulk boolean false true lays out the cells of its child with data-source a page at a time, straight from the data. See Bulk Records

A list of items, each marked with a bullet drawn as a shape or a number the engine writes. Its children are li items. The items go top to bottom with gap between them, and a list inside an item nests. It takes the attributes of a box, and width. See List.

Attribute Type Default Description
type string bullet bullet marks each item with a shape, number with a number
bullet string by depth The shape of a bullet list: disc circle square dash. Without it a list uses a disc, one inside a bullet list a circle, and one inside that a square
format string decimal How a number list writes its numbers: decimal lower-alpha upper-alpha lower-roman upper-roman
start integer 1 The number of a number list’s first item
prefix string — Text before each number of a number list
suffix string . Text after each number of a number list
indent token/length 24pt The width of the marker’s column: the words of an item start this far from the list’s left edge, at every level
bulk boolean false true lays out the items of its li with data-source a page at a time, straight from the data. See Bulk Records
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

One item of a list: a box that holds what a layout holds, beside the item’s marker. Its words go in a text. It takes the attributes of a box, which go around the marker and the content together, and its gap goes between its children: the gap of the list unless the item sets one. data-source repeats the item once for each entry of the data, and the numbers follow what is made. See List.

Single-child container with padding, border, and background. Always centres its child, so it takes no gap, align or justify, and a second child is an error.

Code, or any text whose spaces and lines matter, in a box. The text is kept as it is written: every space, and a new line wherever one is written, except the line break after the start tag and the indent of the line the end tag stands on. A line longer than the box wraps at a space, and a word with none breaks at the last character that fits. The box fills the width, in Courier on a light tint with padding m, and splits across pages between lines. Children: span, which colors parts of the code. See Code.

Attribute Type Default Description
font string Courier Font for the code
font-size token/length inherit Font size for the code
color color inherit Color of the code
padding spacing m Space between the edge of the box and the code
background color #f3f4f6 The tint of the box
border, radius, opacity, shadow, width, height As on a box
tab-size integer 4 How many columns a tab fills to, 1 to 16
line-height number or token 1.2 The distance between lines, as a factor of the font size
widows, orphans integer 2 The fewest lines of the code that may stand alone at the top or the bottom of a page when it splits
paginate, debug As on a box
data-value string — Dot-path to a string that replaces the code, as it is
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Paragraph or inline text.

Attribute Type Default Description
font string inherit, else the document’s font, or Helvetica Font name
font-size token/length inherit, else m (11pt) Font size
color color the nearest box’s, else #1a1a1a Text color. A text that sets none takes the color of the nearest box that sets one, else the text color: a color named text in tokens changes the default
align string left left center right justify. Not inherited: on a box, align places the children
width token/length — Constrain text block width
line-height number or token 1.2 (m) The distance between lines, as a factor of the font size: a number above 0, or a name from the line-height row of tokens
max-lines integer — The most lines drawn. Only whole lines are drawn, and the rest of the text is dropped. No cap by default: the text wraps whole. See Capping a text
ellipsis boolean false End the last line drawn in an ellipsis when max-lines drops text. With no max-lines it changes nothing
role string — h1 … h6: makes the text a heading, which a tagged document, with pdfua or a pdfa of level a, tags as one. It changes nothing a page shows. A document that is not tagged ignores it
widows integer 2 The fewest lines, 1 to 10, that a split paragraph may carry to the top of the next page. 1 turns it off
orphans integer 2 The fewest lines, 1 to 10, that a split paragraph may leave at the bottom of a page. 1 turns it off
capture string — Records the words of this text under a name, for a header or a footer to show. See Running headers
capture-ref string — In a region: shows what was recorded under the name, as of the page the text is on, in place of words of its own
capture-mode string last With capture-ref: first or last, which of the texts captured on the page it shows
capture-fallback string — With capture-ref: what it shows until something has been captured in the section
paginate string — Page breaks: no break-before break-after keep-next. See Page breaks
debug boolean false Draw the box outline
data-value string — Dot-path to a scalar value that replaces the text
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Children: span for inline style overrides, code-span for a run of code, and fn for a footnote.

Inline text with overridden style.

Attribute Type Description
font string Font override
color color Color override
href URL Makes the span a link: a URL, or #id to jump to the bookmark with that id
bookmark-ref string Makes the span a cross-reference to the bookmark with that id: a link to it. In its words, {bookmark-page} prints the page the bookmark is on, as that page’s footer prints it, and {bookmark-label} its label. An id no bookmark has, another {…} in the words, and href beside it are errors. See Referring to a bookmark
underline boolean Underline text
strike boolean Strikethrough text

A space falls between a span and the text around it only where the text has whitespace there. See Spaces around a span.

A run of code inside a text: its words in Courier on a light tint, drawn behind them. White space in it collapses as in the text around it, and like a span it is not broken inside. See Code.

Attribute Type Default Description
font string Courier Font override
color color the text’s Color override
background color #f3f4f6 The tint behind the words

A footnote, inside a text of the layout. Its place in the text shows a small raised number, and the words it holds go at the bottom of the page where that number lands, under a short rule, in the order of the numbers. It takes no attributes, and holds words and span elements. A page with notes has less room for its text, so a line whose note would not fit moves to the next page with it. The numbers start over where footnote-counter on the document or a section says.

Only a text of the layout can hold one: an fn in a text-at, a table or a region is an error. See Footnote.

Horizontal (or vertical) rule.

Attribute Type Default Description
direction string horizontal horizontal or vertical
color color #000000 Line color
thickness token/length 1pt Line thickness. Tokens are border sizes: xs 0.5pt up to xxl 4pt
debug boolean false Draw the box outline
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Inline image.

Attribute Type Default Description
name string — Required. Asset name
alt string — What the image shows, which a screen reader reads in a tagged document, with pdfua or a pdfa of level a; alt="" marks it as decoration. A PDF/UA document needs it on each image outside a header or a footer; at level a without pdfua, an image without it is decoration. A document that is not tagged ignores it
width token/length/fill — Width, or fill: as wide as the room the image has. Without height, the height follows the image’s proportions
height token/length — Height: a length, or a name from the height row of tokens. With both, they are a maximum: the image is never stretched. With width="fill", a limit
padding spacing 0 Space around the picture, inside the box
background color — Background of the box around the picture
border BorderValue — Border, drawn on the edge of the box
radius token/length 0 Corner radius: rounds the box, and clips the picture to rounded corners
paginate string — Page breaks: no break-before break-after keep-next. See Page breaks
debug boolean false Draw the box outline
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

width="fill" makes the picture as wide as the room it has: the column it is in, what the line of a row leaves after the other children (shared with the other fill children), or a table cell. Its height follows its proportions, and a height limits it. See Image.

An image that sets padding, background or border is a box around its picture: width and height size the picture, and the box is larger by the padding. With width="fill" the box takes the room, and the picture fills what the padding leaves. A radius alone clips the picture to rounded corners. See Image.

A rectangle, a circle or an ellipse in the flow, for a status dot, a color swatch or a progress bar. It takes room as an image does, has no children, and is drawn centered in its box. For a shape at a place on the page, use a layer. See Shape.

Attribute Type Default Description
type string — Required. rect circle ellipse
width token/length — Width of a rect or an ellipse, which need it
height token/length — Height of a rect or an ellipse, which need it: a length, or a name from the height row of tokens
r length — Radius of a circle, which needs it. Its box is the square of side 2r
radius token/length — Corner radius of a rect
fill color or gradient:name — Fill: a color, or a gradient that spans the shape
stroke color — Stroke color
stroke-width length — Stroke width
stroke-dash string — Dash pattern: "4 3"
opacity 0–1 1 How opaque the shape is
debug boolean false Draw the box outline
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content
Attribute Type Default Description
cols string — Required. Column widths, separated by spaces, in fr, pt, mm, in or %, or auto: "1fr 2fr", "100pt 1fr", "40mm 1fr". An entry that is none of these is an error
border BorderValue — Grid lines between and around the cells
stripe color — Alternating row background
gap token/length 0 Space between columns and between rows
padding spacing 0 Space between the table’s edge and its content. Not cell padding: set it on each td
background color or gradient:name — Background behind the whole table. A gradient spans the table
width token/length — Fixed width
height token/length/fill/full — A length fixes the height, as a length or a name from the height row of tokens
paginate string — Page breaks: no break-before break-after keep-next. See Page breaks
debug boolean false Draw the box outline
bulk boolean false true lays out the rows of its tr with data-source a page at a time, straight from the data. See Bulk Records
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

A table holds an optional thead and any number of tr.

Attribute Type Description
background color or gradient:name Row background. A gradient spans the row
keep string tr only. with-next keeps the row on the same page as the row after it: a run of such rows and the row that ends it move to the next page together. See Table
ocg string print or screen: shown only in print, or only on screen. See Print and screen content

thead repeats at the top of every page. Both hold td cells.

Takes the shared box attributes, except width, which includes color, opacity and shadow. It accepts paginate, which has no effect on a cell, since a row never splits. Its own attributes:

Attribute Type Default Description
align string fill start center end. By default children fill the cell width
valign string top top middle bottom
colspan integer 1 How many of the table’s columns the cell spans: as wide as them and the gaps between them. A row that spans more columns than cols names is an error. See Table
rowspan integer 1 How many rows the cell spans: as tall as them and the gaps between them, with the rows under it leaving its columns out. The rows it spans stay on one page. A row with a cell too many for the free columns, and a span past the last row, are errors; a thead takes no rowspan. See Table
Attribute Type Default Description
type string — Required. qr datamatrix pdf417 code128 code39 ean13 ean8 upca gs1-128 gs1-datamatrix. See Barcode
data string — Required. Barcode data payload
alt string — What the barcode is for, which a screen reader reads in a tagged document, with pdfua or a pdfa of level a, in place of its data: “QR code to pay this invoice”. alt="" marks it as decoration. A PDF/UA document needs it on each barcode outside a header or a footer; at level a without pdfua, a barcode without it is decoration. A document that is not tagged ignores it
width token/length — Width. Without height, the height follows the barcode’s proportions
height token/length — Height of the whole barcode, with the digits of hrt inside it: a length, or a name from the height row of tokens. With both, they are a maximum: the barcode is never stretched
ec string — Error correction: L M Q H for a qr (M without it), 0 to 8 for a pdf417
hrt boolean false Human-readable text below a linear barcode: code128 code39 ean13 ean8 upca gs1-128
rows integer — Rows of a pdf417 (3 to 90) or a Data Matrix (a size of the standard’s)
columns integer — Columns of a pdf417 (1 to 30 codewords) or a Data Matrix (a size of the standard’s)
check boolean false The mod 43 check character of a code39
data-value string — Dot-path to a scalar value that replaces the data the barcode encodes
color color #000000 Bar color
background color — Background color
paginate string — Page breaks: no break-before break-after keep-next. See Page breaks
debug boolean false Draw the box outline
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Clickable hyperlink wrapper.

Attribute Type Description
href URL Required. Link target: a URL, or #id to jump to the bookmark with that id. Fixed: data-value does not change it
gap spacing Gap between child elements
debug boolean Draw the box outline
ocg string print or screen: shown only in print, or only on screen. See Print and screen content

In an entry of a table of contents, href="#" on a link or a span jumps to that entry’s bookmark.

An entry of the PDF’s outline and a target for href="#id" links and bookmark-ref cross-references. It draws nothing, and marks the element that follows it, which must be in the same container. Directly inside a section, as its first child, it marks the section’s first page. Not allowed in a layer. See Bookmark.

Attribute Type Default Description
label string — Required. The text of the entry, in the outline and in a table of contents
level integer 1 Depth in the outline, 1 to 6. An entry nests under the closest entry before it with a lower level
id string from label The name links jump to. Without it, the label lowercased with other characters than letters and digits turned into hyphens, and -2, -3 added when the id is taken. Two bookmarks may not have the same id
ref-only boolean false true leaves the bookmark out of the outline and the table of contents; links and cross-references still reach it

PDF form field.

Attribute Type Default Description
type string — Required. text checkbox dropdown radio button
name string — Required. Field name in the PDF form
value string — Default value
label string — Visible label (checkbox, radio, button)
options string — Comma-separated options (dropdown)
group string — Radio group name
checked boolean false Initial checked state (checkbox/radio)
required boolean false Mark field as required
readonly boolean false Prevent editing
max-len integer — Maximum text length
action-url URL — Submit URL (button)
width token/length — Field width
height token/length — Field height: a length, or a name from the height row of tokens
debug boolean false Draw the box outline
ocg string — screen: shown only on screen. print is an error: a field in print content could be filled nowhere. See Print and screen content

Pinned header or footer that repeats across pages. Only allowed directly inside layout. pin chooses the edge wherever the region is written among the flow, and regions on one edge stack in the order written. In its text, {page} is the page’s number and {pages} how many pages its run has (see Page numbers), and a text with capture-ref shows what the flow captured on its page (see Running headers).

Attribute Type Default Description
pin string — Required. top or bottom, or inset for a block inside the section’s columns. left and right pass validation but are not implemented yet
page string each each first last odd even, or numbers and ranges such as 2-last. odd and even follow the number printed on the page, and the rest count the section’s own pages: see Odd and even pages. An inset on last goes on the last page of the flow filled without it, and stays there if it pushes text on to a new page
top length — An inset only, and required with it: how far below the top of the columns it starts
height length — An inset only, and required with it: how tall it is. Content taller than it is clipped at its foot; an inset that reaches below the room the headers and footers leave is an error
col whole number 1 An inset only: the column it starts in, from 1
colspan whole number 1 An inset only: how many columns it covers. Past the section’s columns is an error
debug boolean false Draw the region’s outline

With pin="inset" the region is an inset: a block at a spot in the section’s columns, which the columns it covers fill above and carry on below. See Insets.

Layer elements live inside a layer, which is a child of section. Positions and sizes take pt, mm or in. A layer reads single values: text-at, img-at, barcode-at and the layer itself take data-if and data-if-not, and text-at and barcode-at take data-value. data-source is not allowed. See Layer.

Fixed content, in the order it is written among the section’s layers and layout.

Attribute Type Default Description
page string each each first last odd even, or numbers and ranges such as 2-last. odd and even follow the number printed on the page, and the rest count the section’s own pages: see Odd and even pages
opacity 0–1 1 Opacity of everything in the layer as one. 0 draws nothing
transform string — translate(x, y), scale(s), rotate(deg, cx, cy) or matrix(a, b, c, d, e, f), with plain numbers
clip string — A rectangle, x y w h, in points from the top left corner of the page: what the layer draws outside it is cut off
font string the document’s font, or Helvetica The font of the text-at in the layer that sets none of its own
font-size token/length m (11pt) The size of the text-at in the layer that sets none of its own
color color #1a1a1a The color of the text-at in the layer that sets none of its own. Defaults to the text color
alt string — In a tagged document, with pdfua or a pdfa of level a, what the layer shows: a screen reader reads it as one figure at the layer’s place. Without it a layer is decoration, which a reader skips with its text
data-if string — Draw the layer only when the value at the path is truthy
data-if-not string — Draw the layer only when the value at the path is falsy
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

A layer cannot contain another layer.

Attribute Type Default Description
x signed length — X of the left edge (or offset from anchor)
y signed length — Y of the top edge (or offset from anchor)
width length — Required. Width
height length — Required. Height
anchor string — Reference point
fill color or gradient:name — Fill: a color, or a gradient that spans the rectangle
stroke color — Border color
stroke-width length 1pt Border width
stroke-dash string — Dash pattern: "4 2"
radius length — Corner radius
shadow string — A hard-edged shadow under the shape: "x y color", with an optional opacity after the color. See Shadow
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content
Attribute Type Default Description
x signed length — X of the left edge of the circle’s box, the square of side 2r around it (or offset from anchor)
y signed length — Y of the top edge of the circle’s box (or offset from anchor)
r length — Required. Radius
anchor string — Reference point
fill color or gradient:name — Fill: a color, or a gradient that spans the circle’s box
stroke color — Border color
stroke-width length 1pt Border width
stroke-dash string — Dash pattern
shadow string — A hard-edged shadow under the shape: "x y color", with an optional opacity after the color
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Takes the same attributes as circle, with rx and ry in place of r. Its box is 2rx wide and 2ry high.

Attribute Type Description
rx length Required. Horizontal radius
ry length Required. Vertical radius
Attribute Type Default Description
x1 signed length — Required. Start X
y1 signed length — Required. Start Y
x2 signed length — Required. End X
y2 signed length — Required. End Y
stroke color #000000 Line color
stroke-width length 1pt Line thickness
stroke-dash string — Dash pattern: "4 2"
line-cap string butt butt round square
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content
Attribute Type Default Description
d string — Required. SVG path data
fill color or gradient:name — Fill: a color, or a gradient that spans the path’s bounding box
stroke color — Stroke color
fill-rule string nonzero nonzero evenodd
stroke-width length 1pt Stroke width
stroke-dash string — Dash pattern
line-cap string butt butt round square
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Text at a fixed place. It is the layout’s text: max-lines, ellipsis and line-height are the layout text’s attributes, with text-at’s own defaults (one line, and a width above 1). Its font, size and color default to its layer’s. Children: span, as in text.

Attribute Type Default Description
x signed length — X of the left edge of the box (or offset from anchor)
y signed length — Y of the top edge of the box (or offset from anchor)
anchor string — Reference point
width length — Width of the box. Without it the text is one line at its natural width
max-lines integer 1 The most lines drawn. Above 1 it needs a width
ellipsis boolean false End the last line drawn in an ellipsis when the text does not fit
line-height number or token 1.2 (m) The distance between lines, as a factor of the font size: a number above 0, or a name from the line-height row of tokens
font string the layer’s font, else the document’s, or Helvetica Font name
font-size token/length the layer’s, else m (11pt) Font size
bold boolean false The bold face of a built-in font
color color the layer’s, else #1a1a1a Text color. A color named text in tokens changes the default
align string left left center right justify, within width
data-value string — Dot-path to a value that replaces the text
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

An image at a fixed place. It needs width or height.

Attribute Type Default Description
name string — Required. Asset name
x signed length — X of the left edge of the box (or offset from anchor)
y signed length — Y of the top edge of the box (or offset from anchor)
anchor string — Reference point
width length — Width. Without height, the height follows the image’s proportions
height length — Height. With both, they are a maximum: the image is never stretched
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

A barcode at a fixed place. It needs width or height.

Attribute Type Default Description
type string — Required. qr datamatrix pdf417 code128 code39 ean13 ean8 upca gs1-128 gs1-datamatrix
data string — Required. Barcode data payload
x signed length — X of the left edge of the box (or offset from anchor)
y signed length — Y of the top edge of the box (or offset from anchor)
anchor string — Reference point
width length — Width. Without height, the height follows the barcode’s proportions
height length — Height of the whole barcode, with the digits of hrt inside it. With both, they are a maximum: the barcode is never stretched
ec string — Error correction: L M Q H for a qr (M without it), 0 to 8 for a pdf417
hrt boolean false Human-readable text below a linear barcode: code128 code39 ean13 ean8 upca gs1-128
rows integer — Rows of a pdf417 (3 to 90) or a Data Matrix (a size of the standard’s)
columns integer — Columns of a pdf417 (1 to 30 codewords) or a Data Matrix (a size of the standard’s)
check boolean false The mod 43 check character of a code39
color color #000000 Bar color
background color — Background color
data-value string — Dot-path to a value that replaces the data the barcode encodes
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

Used by layer elements (x/y are offsets from the anchor point, and the element’s matching point is placed there). The points are on the whole page, not inside the margin:

Value Description
top-left Top-left corner of the page
top-center Top centre
top-right Top-right corner
center-left Middle of the left edge
center Page centre
center-right Middle of the right edge
bottom-left Bottom-left corner
bottom-center Bottom centre
bottom-right Bottom-right corner