Dynamic Images

Overview

Dynamic images are image elements whose source URL comes from your API data rather than being set at design time. This lets you display different images in each generated PDF — user avatars, product photos, company logos, QR codes, and more.

Setting Up Dynamic Images

1. Add an Image element to the canvas
2. In the inspector, switch the image source from Upload to Dynamic
3. Enter a field key (e.g., company_logo)
4. Optionally set a fallback image for when no URL is provided

At generation time, pass the image URL in your API data:

{
  "templateId": "tmpl_badge_001",
  "data": {
    "employee_name": "Jane Smith",
    "employee_photo": "https://cdn.example.com/photos/jane-smith.jpg",
    "company_logo": "https://cdn.example.com/logos/acme.png"
  }
}

Common Use Cases

User Avatars & Photos

Display employee photos on badges, certificates, or ID cards:

{
  "data": {
    "employee_photo": "https://cdn.example.com/photos/jane.jpg"
  }
}

Company Logos

Use a single template for multiple clients by passing each client's logo:

{
  "data": {
    "client_logo": "https://client-assets.example.com/acme-logo.png"
  }
}

QR Codes

Generate QR codes dynamically using a QR code API and pass the image URL:

{
  "data": {
    "ticket_qr": "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=TICKET-12345"
  }
}

Barcodes

Add barcodes to shipping labels, inventory documents, and tickets:

{
  "data": {
    "barcode_image": "https://barcodes.example.com/generate?type=code128&value=SKU-90210"
  }
}

Product Photos

Include product images in catalogs, receipts, and quotes:

{
  "data": {
    "product_image": "https://cdn.store.com/products/widget-pro.jpg"
  }
}

Fallback Images

Set a fallback image in the inspector that displays when:

• The field key is not present in the API data
• The image URL returns a 404 or is unreachable
• The URL is empty or null

Common fallbacks include a placeholder avatar, generic logo, or a transparent 1x1 pixel image.

Image URL Requirements

• Images must be publicly accessible — no authentication required
• HTTPS URLs are recommended for security
• Supported formats: PNG, JPEG, SVG, WebP
• Maximum image size: 5MB
• Images should load within 10 seconds or they'll be skipped

Performance Tips

• Use optimized images — resize to the exact dimensions you need before passing the URL
• Prefer JPEG for photos, PNG for logos with transparency
• Use a CDN to serve images for faster loading
• Keep image file sizes under 1MB when possible for faster PDF generation

Next Steps

• Image Elements — Static and uploaded images
• Image Optimization — Optimize for quality and size
• Data Binding — Dynamic data fundamentals