Dynamic data
Dynamic data allows you to insert placeholders into your template that get replaced with real values when a PDF is generated. This is how you create reusable templates — design once, generate as many PDFs as you need with different data each time.
Placeholders use the syntax {{data.fieldName}} and can be used in most building blocks: text, images, tables, QR codes, and barcodes.
You can also transform and compute values inside placeholders using formatters and expressions — for example, formatting a number as currency or calculating a total. See Expressions and formatters for details.
How to name dynamic data fields
Third-party integrations
If PDFs will be generated from third-party software that integrates with PDFSamurai, you must use the exact field names provided by that software. The integrating software should give you the list of available dynamic field names.
Standalone
If you are using PDFSamurai both to design the template and to generate the PDF documents, you can name the dynamic fields however you want.
The dynamic data modal
When generating a PDF — either from the editor or from the dashboard — if the template contains dynamic data placeholders, the dynamic data modal is shown so you can fill in the values. In the editor, you can also open it at any time by clicking the button in the top bar.
The modal has two tabs:
- Form — The editor automatically detects all dynamic data placeholders used in your template and displays them as form fields. This makes it easy to fill in values without writing JSON manually.
- JSON — A JSON editor pre-filled with all the placeholder keys from your template. You only need to fill in the values.
The values you enter here are used for the live preview and when generating a PDF.
Using dynamic data in building blocks
Each building block supports dynamic data in a different way:
| Building block | Where to use placeholders | Example |
|---|---|---|
| Text | Inline within content and in links | Hello {{data.customerName}} |
| Image | Via the "From data" tab in the properties panel | Field name pointing to a URL or base64 string |
| Table | In repeatable rows bound to an array | {{data.items[].productName}} |
| QR Code | In the text property | {{data.ticketUrl}} |
| Barcode | In the value property | {{data.trackingNumber}} |
See each building block's page for detailed usage instructions.
Accessing list data
You can reference items in a list (array) in two ways:
By index
Use a specific index to access a single item from a list anywhere in your template:
{{data.items[0].name}}
This is useful when you need a specific item from a list — for example, the first product in an order.
In repeatable table rows
Inside a repeatable table row, you don't need to specify an index. The row automatically iterates over the list, so you can reference fields directly:
{{data.items[].name}}
Since the row already knows which list it belongs to, you can also use the short syntax:
{{data.name}}
Both forms are equivalent inside a repeatable row. The table will generate one row for each item in the list.
Accessing parent and root data
Inside a repeatable row, {{data.fieldName}} refers to a field of the current list item. To access data outside of the current list, use $parent to go up one level:
{{data.$parent.companyName}}
In nested tables (a repeatable row inside another repeatable row), you can chain $parent to go up multiple levels:
{{data.$parent.$parent.someField}}
To access the root level directly regardless of nesting depth, use $root:
{{data.$root.companyName}}
Layers and dynamic data
All layers in the template — body, header, footer, and background — have access to the same dynamic data.
Page metadata
In the header, footer, and background layers, you also have access to special page metadata fields:
{{meta.page}}— The current page number.{{meta.totalPages}}— The total number of pages in the document.
For example, to display page numbers in a footer text element:
Page {{meta.page}} of {{meta.totalPages}}
Page metadata is only available in the header, footer, and background layers. It cannot be used in the body layer.