Image Support Guide

Comprehensive guide to image rendering options in VaultPDF, including standalone images, image grids, and inline images in tables and cards. Supports both SharePoint asset paths and Base64 data URIs.

This guide covers all three image rendering options available in VaultPDF: standalone images, image grids, and inline images in tables and cards. All image nodes support both SharePoint asset paths and direct Base64 data URIs.

Overview

VaultPDF provides flexible image support for:

Single images with sizing and alignment control
Image grids for layouts like hazard pictograms or classification icons
Inline images in table columns and card fields
Conditional visibility with true or false logic, or data-driven conditions
Dual source formats — SharePoint assets or Base64 data URIs

Core Concepts

Image Source Format

Every image supports two source formats:

1. SharePoint Asset Path (Recommended)

{
  "src": "Hazard/pictograms/toxic.png",
  "library": "assets"
}

How it works:

Fetches from SharePoint/assets/Hazard/pictograms/toxic.png
Automatically converted to Base64 during PDF generation
Supports nested paths: "Folder/SubFolder/image.png"
Default library: "assets" (can be overridden to "media", "images", etc.)

2. Direct Base64 Data URI

{
  "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEA..."
}

How it works:

Already Base64-encoded
No asset fetch needed — embeds directly
Useful for dynamically generated images (QR codes, charts) or pre-encoded backend data
No library selection needed
Best practice: Provide in data payload, NOT in template definition
Template should reference a data field: "src": "{{qrCodeData}}"
Backend pre-encodes and supplies the Base64 in the data

Conditional Visibility

All image nodes support conditional visibility:

{
  "visible": true,                    // Always visible
  "visible": false,                   // Always hidden
  "visible": "{{showHazards}}",      // Data-driven: depends on payload
  "visible": "{{showImages && user.role === 'admin'}}"  // Complex logic
}

Option 1: Standalone Image Block

Single image with optional title, sizing, and alignment.

Basic Configuration

{
  "type": "image",
  "props": {
    "title": "Toxic Substance Classification",
    "src": "Hazard/pictograms/toxic.png",
    "library": "assets",
    "width": 120,
    "height": 120,
    "alignment": "center",
    "visible": true
  }
}

Properties

Property	Type	Default	Description
`title`	string	—	Optional label above the image
`src`	string	—	Required - Asset path or Base64 data URI
`library`	string	`"assets"`	SharePoint library name (ignored for Base64)
`width`	number	100	Image width in points
`height`	number	100	Image height in points
`alignment`	`'left'` \| `'center'` \| `'right'`	`"center"`	Horizontal alignment
`visible`	boolean or string	true	Conditional visibility

Examples

Example 1: Asset-Based Image from SharePoint

{
  "type": "image",
  "props": {
    "title": "Product Label",
    "src": "ProductImages/label_2024.png",
    "library": "assets",
    "width": 200,
    "height": 150,
    "alignment": "center"
  }
}

Example 2: Base64 Data URI

{
  "type": "image",
  "props": {
    "title": "Generated QR Code",
    "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "width": 150,
    "height": 150,
    "alignment": "center"
  }
}

Example 3: Conditional Visibility

{
  "type": "image",
  "props": {
    "title": "Company Logo",
    "src": "Branding/logo_full.png",
    "library": "assets",
    "width": 180,
    "height": 80,
    "alignment": "center",
    "visible": "{{isOfficialDocument}}"
  }
}

Render logic:

If isOfficialDocument === true in payload → image displays
If isOfficialDocument === false → image hidden
If isOfficialDocument undefined → defaults to hidden

Example 4: Nested Asset Folder

{
  "type": "image",
  "props": {
    "title": "Import Certificate",
    "src": "Compliance/Certifications/2024/ISO-9001.png",
    "library": "media",
    "width": 250,
    "height": 300,
    "alignment": "left"
  }
}

Option 2: Image Grid Block

Display multiple images in a grid layout. Perfect for hazard pictograms, classification icons, or image galleries.

Basic Configuration

{
  "type": "image_grid",
  "props": {
    "title": "Hazard Classification System",
    "library": "assets",
    "columnsPerRow": 5,
    "spacing": 12,
    "visible": true
  },
  "images": [
    {
      "src": "Hazard/pictograms/toxic.png",
      "label": "Toxic",
      "width": 60,
      "height": 60
    },
    {
      "src": "Hazard/pictograms/flammable.png",
      "label": "Flammable",
      "width": 60,
      "height": 60
    },
    {
      "src": "Hazard/pictograms/oxidizer.png",
      "label": "Oxidizer",
      "width": 60,
      "height": 60
    }
  ]
}

Grid Properties

Property	Type	Default	Description
`title`	string	—	Optional title above the grid
`library`	string	`"assets"`	Default library for all images (can be overridden per image)
`columnsPerRow`	number	5	Number of images per row
`spacing`	number	10	Spacing between images in points
`visible`	boolean or string	true	Conditional visibility for entire grid

Image Properties

Each image in the images array:

Property	Type	Default	Description
`src`	string	—	Required - Asset path or Base64 URI
`label`	string	—	Optional label below the image
`width`	number	60	Image width in points
`height`	number	60	Image height in points

Examples

Example 1: Hazard Pictograms (Like Your Shipping Report)

{
  "type": "image_grid",
  "props": {
    "title": "GHS Hazard Classifications",
    "library": "assets",
    "columnsPerRow": 5,
    "spacing": 15,
    "visible": "{{includeHazardInfo}}"
  },
  "images": [
    {
      "src": "GHS/pictograms/acute-toxicity.png",
      "label": "Acute Toxicity",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/carcinogenicity.png",
      "label": "Carcinogenicity",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/environment-hazard.png",
      "label": "Environmental Hazard",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/exclamation-mark.png",
      "label": "Irritant",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/flame.png",
      "label": "Flammable",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/exploding-bomb.png",
      "label": "Explosive",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/flame-circle.png",
      "label": "Oxidizing",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/gas-cylinder.png",
      "label": "Compressed Gas",
      "width": 70,
      "height": 70
    },
    {
      "src": "GHS/pictograms/corrosion.png",
      "label": "Corrosive",
      "width": 70,
      "height": 70
    }
  ]
}

Example 2: Product Classification with Mix of Sources

{
  "type": "image_grid",
  "props": {
    "title": "Product Classifications",
    "columnsPerRow": 4,
    "spacing": 10
  },
  "images": [
    {
      "src": "Categories/food.png",
      "label": "Food",
      "width": 50,
      "height": 50
    },
    {
      "src": "data:image/png;base64,iVBORw0KGgoAAAANS...",
      "label": "Electronics",
      "width": 50,
      "height": 50
    },
    {
      "src": "Categories/pharma.png",
      "label": "Pharmaceutical",
      "width": 50,
      "height": 50
    },
    {
      "src": "Categories/chemical.png",
      "label": "Chemical",
      "width": 50,
      "height": 50
    }
  ]
}

Example 3: Thumbnail Gallery

{
  "type": "image_grid",
  "props": {
    "title": "Document Attachments",
    "columnsPerRow": 3,
    "spacing": 20,
    "visible": "{{attachmentCount > 0}}"
  },
  "images": [
    {
      "src": "Attachments/invoice_scan.png",
      "label": "Invoice",
      "width": 80,
      "height": 100
    },
    {
      "src": "Attachments/receipt.png",
      "label": "Receipt",
      "width": 80,
      "height": 100
    },
    {
      "src": "Attachments/packing_slip.png",
      "label": "Packing Slip",
      "width": 80,
      "height": 100
    }
  ]
}

Option 3: Inline Images in Tables & Cards

Render images directly in table columns or card fields.

Table Column Configuration

Add to any table column definition:

{
  "key": "hazardIcon",
  "label": "Hazard Icon",
  "imageField": true,
  "imageLibrary": "assets",
  "imageWidth": 40,
  "imageHeight": 40,
  "imageAlign": "center"
}

Column Properties

Property	Type	Default	Description
`imageField`	boolean	false	Treat cell value as image source path
`imageLibrary`	string	`"assets"`	Library name for asset paths (ignored for Base64)
`imageWidth`	number	40	Image width in points
`imageHeight`	number	40	Image height in points
`imageAlign`	`'left'` \| `'center'` \| `'right'`	`"center"`	Horizontal alignment in cell

Examples

Example 1: Hazard Icons in Table

Table schema:

{
  "type": "table",
  "title": "Chemical Inventory",
  "columns": [
    {
      "key": "chemicalName",
      "label": "Chemical",
      "width": "40%"
    },
    {
      "key": "hazardIcon",
      "label": "Primary Hazard",
      "imageField": true,
      "imageLibrary": "assets",
      "imageWidth": 50,
      "imageHeight": 50,
      "imageAlign": "center"
    },
    {
      "key": "quantity",
      "label": "Quantity (L)",
      "format": "number"
    }
  ]
}

Data payload:

{
  "rows": [
    {
      "chemicalName": "Hydrochloric Acid",
      "hazardIcon": "Hazard/pictograms/corrosion.png",
      "quantity": 250
    },
    {
      "chemicalName": "Acetone",
      "hazardIcon": "Hazard/pictograms/flame.png",
      "quantity": 100
    },
    {
      "chemicalName": "Sodium Hypochlorite",
      "hazardIcon": "Hazard/pictograms/environment-hazard.png",
      "quantity": 500
    }
  ]
}

Example 2: Product Images with Base64

Table schema:

{
  "type": "table",
  "title": "Product Catalog",
  "columns": [
    {
      "key": "productName",
      "label": "Product",
      "width": "60%"
    },
    {
      "key": "thumbnail",
      "label": "Image",
      "imageField": true,
      "imageWidth": 60,
      "imageHeight": 60,
      "imageAlign": "center"
    }
  ]
}

Data payload (pre-encoded Base64):

{
  "rows": [
    {
      "productName": "Product A",
      "thumbnail": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEA..."
    },
    {
      "productName": "Product B",
      "thumbnail": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
    }
  ]
}

Example 3: Card Field with Image

Card schema:

{
  "type": "card",
  "title": "Product Details",
  "fields": [
    {
      "key": "productImage",
      "label": "Product Image",
      "imageField": true,
      "imageWidth": 150,
      "imageHeight": 150,
      "imageAlign": "center"
    },
    {
      "key": "productName",
      "label": "Product Name"
    },
    {
      "key": "price",
      "label": "Price",
      "format": "currency"
    }
  ]
}

Data payload:

{
  "productImage": "Products/package_front.png",
  "productName": "Premium Coffee Blend",
  "price": 29.99
}

Real-World Example: Shipping Report with Hazard Pictograms

Complete document combining all image types:

{
  "sections": [
    {
      "type": "section",
      "title": "Shipping Report",
      "children": [
        {
          "type": "note_block",
          "variant": "info",
          "title": "Hazardous Materials Notice",
          "description": "This shipment contains materials classified as hazardous. All items are packaged and labeled according to GHS regulations."
        },
        {
          "type": "image",
          "props": {
            "title": "Third Coast Terminals Logo",
            "src": "Branding/terminals_logo.png",
            "library": "assets",
            "width": 200,
            "height": 80,
            "alignment": "center"
          }
        },
        {
          "type": "table",
          "title": "Shipment Contents",
          "columns": [
            {
              "key": "system",
              "label": "Product"
            },
            {
              "key": "hazardIcon",
              "label": "Hazard",
              "imageField": true,
              "imageWidth": 45,
              "imageHeight": 45
            },
            {
              "key": "quantity",
              "label": "Quantity (Gal)"
            }
          ]
        },
        {
          "type": "image_grid",
          "props": {
            "title": "GHS Hazard Classifications Applicable to This Shipment",
            "columnsPerRow": 5,
            "spacing": 15,
            "visible": "{{includeHazardPictograms}}"
          },
          "images": [
            {
              "src": "GHS/acute-toxicity.png",
              "label": "Acute Toxicity"
            },
            {
              "src": "GHS/carcinogenicity.png",
              "label": "Carcinogenicity"
            },
            {
              "src": "GHS/flame.png",
              "label": "Flammable"
            },
            {
              "src": "GHS/environment.png",
              "label": "Environmental"
            },
            {
              "src": "GHS/corrosion.png",
              "label": "Corrosive"
            }
          ]
        },
        {
          "type": "card",
          "title": "Handling Instructions",
          "fields": [
            {
              "key": "handlingImage",
              "label": "Safety Information",
              "imageField": true,
              "imageWidth": 200,
              "imageHeight": 200
            },
            {
              "key": "instructions",
              "label": "Instructions"
            }
          ]
        }
      ]
    }
  ]
}

Asset Path Reference

Standard Folders

Your SharePoint assets library likely has this structure:

SharePoint/assets/
├── Branding/
│   ├── logo_full.png
│   ├── logo_small.png
│   └── watermark.png
├── Hazard/
│   ├── pictograms/
│   │   ├── toxic.png
│   │   ├── flammable.png
│   │   ├── corrosion.png
│   │   └── ...
│   └── classifications/
│       └── ...
├── Products/
│   ├── package_front.png
│   ├── label.png
│   └── ...
├── GHS/
│   ├── acute-toxicity.png
│   ├── carcinogenicity.png
│   ├── flame.png
│   └── ...
└── Compliance/
    ├── Certifications/
    │   └── 2024/
    │       ├── ISO-9001.png
    │       └── ...
    └── Approvals/
        └── ...

Path Format Examples

Description	Path
Direct in assets folder	`"logo.png"`
Subfolder	`"Branding/logo_full.png"`
Nested folder	`"Hazard/pictograms/toxic.png"`
Date-based folder	`"Compliance/Certifications/2024/ISO-9001.png"`

Troubleshooting

Image Not Displaying

Problem: Image does not appear in PDF

Solutions:

Asset path incorrect - Verify path exists in SharePoint: assets/Hazard/pictograms/toxic.png
Base64 format invalid - Ensure data URI starts with data:image/png;base64,
File permissions - Check that the asset is readable by the service
Visibility hidden - Check visible property or conditional logic

Image Distorted or Sized Wrong

Problem: Image appears stretched, squashed, or tiny

Solutions:

Width or height mismatch - Use correct aspect ratio (for example, 100×100 for square images)
Oversized container - Reduce width or height values for smaller displayed size
Grid sizing - Adjust columnsPerRow and spacing for proper grid layout

Grid Images Not Aligned

Problem: Images in grid do not align properly

Solutions:

Inconsistent image sizes - Use same width and height for all images in grid
Column count too high - Reduce columnsPerRow if images are too small
Spacing too large - Decrease spacing value

Asset Library Error

Problem: "Library not found" or "Asset fetch failed"

Solutions:

Wrong library name - Use correct library: "assets", "media", "images"
Library not enabled - Check SharePoint configuration allows access
Path has spaces - URL-encode spaces: "My Documents" becomes "My%20Documents"

Performance Considerations

Base64 vs. Asset Paths

Aspect	Asset Path	Base64 URI
Template size	✅ Smaller (reference only)	❌ Larger (full data embedded)
Final PDF size	Smaller (asset fetched at runtime)	Larger (~33% encoding overhead)
Generation time	Slightly slower (fetch + convert)	Immediate (pre-encoded)
Best for	Static images, template size matters	Dynamic or generated images, pre-encoded data
Where to use	In template	In data payload
Example	Template: `"src": "Hazard/toxic.png"`	Data: `{"hazardIcon": "data:image/png;base64,iVB..."}`

Recommendations

Asset Paths (Recommended):

Keep templates small and reusable
Use for static images (logos, pictograms, classifications)
Define in template, fetch at document generation time
Example: "src": "Hazard/pictograms/toxic.png"

Base64 URIs (For Dynamic Content):

Use for dynamically generated images (QR codes, charts, generated reports)
Provide in data payload, NOT hardcoded in template
Pre-encoded in backend before passing to template
Do not embed large Base64 strings directly in .vpdf files
Example: Pass from data: {"qrCode": "data:image/png;base64,..."}

Performance Tips

Limit grid images to fewer than 50 images per grid to maintain performance
Resize images in SharePoint before uploading (typical size: 200×200 for icons, 500×500 for detailed)
Prefer asset paths in templates to keep template files small
Pre-generate Base64 in backend rather than encoding in template logic

Available Icons

When using images in tables with conditional styling, you can combine images with icons. Here are the available icons:

Status Icons: check, circlealert, warning, clock, status, x
Info Icons: info, tag, star
Content Icons: file-text, file, package, list, image
System Icons: building, shield, barcode, phone, email, link
Form Controls: checkbox-checked, checkbox-unchecked, radio-checked, radio-unchecked
Percent: percent

For example, in conditional styles:

{
  "value": "HAZARD",
  "icon": "circlealert",
  "color": "#D32F2F"
}

Image Support Guide

On this page