Templates

Templates define the layout and content of your documents. They can be created in the dashboard’s visual editor or defined as JSON and sent inline with render requests.

Template Structure

Every template follows this structure:

{
  "formatVersion": 1,
  "meta": {
    "name": "Shipping Label",
    "description": "4x6 shipping label with barcode",
    "tags": ["shipping", "labels"]
  },
  "dimensions": {
    "width": "4in",
    "height": "6in",
    "safeMargin": "3mm"
  },
  "schema": { ... },
  "sample": { ... },
  "elements": [ ... ]
}

Top-Level Fields

Field	Type	Required	Description
formatVersion	number	Yes	Must be 1.
meta	object	Yes	Template metadata.
meta.name	string	Yes	Template name.
meta.description	string	No	Human-readable description.
meta.tags	string[]	No	Organizational tags.
dimensions	object	Yes	Document dimensions.
dimensions.width	string	Yes	Width with unit (e.g., "4in", "100mm").
dimensions.height	string	Yes	Height with unit.
dimensions.safeMargin	string	No	Safe margin inset from edges.
schema	object	No	JSON Schema for validating data at render time.
sample	object	No	Sample data used for dashboard thumbnails.
elements	array	Yes	Array of design elements.

Supported Units

Dimensions and positions accept values with these units:

Unit	Example	Description
in	"4in"	Inches
mm	"100mm"	Millimeters
cm	"10cm"	Centimeters
pt	"288pt"	Points (1/72 inch)
px	"384px"	Pixels (at 96 DPI)

Elements

Elements are the building blocks of a template. Each element has a type, position, size, and type-specific properties.

Common Element Fields

Field	Type	Required	Description
id	string	Yes	Unique element identifier.
type	string	Yes	Element type (see below).
position	object	Yes	Positioning configuration.
width	string	Yes	Element width with unit.
height	string	Yes	Element height with unit.
rotation	number	No	Rotation in degrees.
visible	string	No	Expression — element is hidden when it evaluates to falsy.

Element Types

Type	Description
text	Text content with font styling. Supports expressions for dynamic content.
barcode	1D barcode (Code 128, Code 39, etc.).
qrcode	QR code.
datamatrix	Data Matrix 2D barcode.
image	Static or dynamic image from a URL.
line	Horizontal or vertical line.
rect	Rectangle with optional fill and border.

Positioning

Elements support two positioning modes:

Absolute — positioned relative to the document origin:

{
  "position": {
    "mode": "absolute",
    "x": "10mm",
    "y": "20mm"
  }
}

Relative — positioned relative to another element:

{
  "position": {
    "mode": "relative",
    "anchor": "other-element-id",
    "offset": { "x": "0mm", "y": "5mm" }
  }
}

Data Binding

Elements can use expressions to dynamically render content from the data object passed at render time.

Content Expressions

Text and barcode elements use the content field:

{
  "type": "text",
  "content": {
    "expression": "data.customer.name"
  }
}

Expressions are JavaScript expressions evaluated at render time. The data object is available in scope.

{
  "content": {
    "expression": "data.quantity + ' x ' + data.productName"
  }
}

Static Content

For static text, use the value field instead of expression:

{
  "content": {
    "value": "SHIP TO:"
  }
}

Conditional Visibility

Any element can be conditionally shown or hidden using the visible field:

{
  "visible": "data.priority === 'rush'"
}

Saved Templates

Templates created in the dashboard are stored and can be referenced by ID in render requests using templateId. Published templates are available to API keys; draft templates are only accessible via the dashboard.

Status	API Key Access	Dashboard Access
Draft	No	Yes
Published	Yes	Yes

Template Slugs

Every template gets an auto-generated slug based on its name (e.g., shipping-label). Slugs are human-readable identifiers you can use as templateId in render requests instead of opaque template IDs.

Slug format: lowercase letters, digits, and hyphens (e.g., product-2x1, shipping-label).

Template Libraries

Templates can belong to a library — a shared collection accessible to any team. Library templates use a qualified slug format: librarySlug:templateSlug (e.g., carbon:product-2x1).

See Template Libraries for details.