Document Stack
Document Stack
Docs

Field Elements

Add dynamic field elements that get replaced with real data at PDF generation time.

What Are Field Elements?

Field elements are the core of Document Stack's dynamic document generation. They look like regular text on the canvas, but when you generate a PDF via the API, each field is replaced with actual data from your JSON payload.

Think of fields as placeholders — {{customer_name}} becomes "Acme Corporation" in the generated PDF.

Adding a Field Element

  1. Click Field in the toolbar (or press F)
  2. Click on the canvas to place the element
  3. In the inspector panel, set the Field Key

The field key is the name you'll use in your API data to fill this field. For example, a field with key customer_name will display whatever value you pass as customer_name in the API request.

Field Key Naming

Field keys are identifiers that map your JSON data to template elements. Follow these conventions:

  • Use snake_case — invoice_number, due_date, customer_email
  • Be descriptive — billing_address is better than addr
  • Keep them unique within a template
  • Avoid special characters — stick to letters, numbers, and underscores

Reuse Field Keys

You can use the same field key on multiple elements. For example, if you want the customer name in both the header and footer, give both fields the key customer_name — they'll both be filled with the same value.

Passing Data via the API

When generating a PDF, include a data object in your API request with keys matching your field keys:

JSON
{
  "templateId": "tmpl_invoice_001",
  "data": {
    "invoice_number": "INV-2026-0042",
    "customer_name": "Acme Corporation",
    "customer_email": "billing@acme.com",
    "due_date": "February 28, 2026",
    "total_amount": "$4,250.00"
  }
}

Each field key in the template is matched against the data object. Unmatched fields display their key name as placeholder text.

Nested Data Access

You can access nested object properties using dot notation in field keys:

JSON
{
  "data": {
    "customer.name": "Acme Corp",
    "customer.address.city": "San Francisco",
    "customer.address.state": "CA"
  }
}

Default Values

In the inspector panel, you can set a default value for any field. If the API data doesn't include a value for that field key, the default is used instead. This is useful for:

  • Optional fields that might not always have data
  • Preview text while designing the template
  • Fallback values like "N/A" or "—"

Styling Fields

Field elements support all the same styling as text elements:

  • Font family, size, weight, and color
  • Text alignment (left, center, right)
  • Line height and letter spacing
  • Text decoration (underline, italic, uppercase)
  • Background color and borders
Style your fields to match the surrounding text. A field with key customer_name next to a "Customer:" label should use the same font size and weight for a cohesive look.

Missing Fields

When a field key in the template doesn't have a matching value in the API data:

  • If a default value is set, it's used
  • If no default is set, the field key name is displayed as-is (e.g., "customer_name")
  • No error is thrown — the PDF still generates

This allows you to generate PDFs with partial data without errors.

Best Practices

  • Name fields descriptively — future you will thank you
  • Set default values for optional fields
  • Document your field keys so API consumers know what data to send
  • Test with realistic data to ensure text fits within element bounds
  • Use the same field key across elements for data that should appear in multiple places

Next Steps

Previous

Image Elements

Next

Icon Elements