Orshot Logo
OrshotDocs
Dynamic Parameters

Interactive Links with .href

Add clickable links to text and image elements in PDF outputs using the .href parameter

Overview

The .href parameter adds clickable hyperlinks to text and image elements in PDF outputs. When users click on these elements in the generated PDF, they'll be redirected to the specified URL.

PDF Only Feature: Links only work in PDF format outputs. They are ignored for PNG, JPEG, and WebP formats.

How It Works

When you add .href to a parameterized text or image element, Orshot:

  1. Validates the URL format
  2. Applies the link as a clickable area in the PDF
  3. Preserves all visual styling while making the element interactive

Syntax

parameterID.href

For multi-page templates:

pageN@parameterID.href

Basic Usage

Text Links

{
  "modifications": {
    "cta_button.href": "https://example.com/signup"
  },
  "response": {
    "format": "pdf"
  }
}

The text element cta_button becomes clickable, redirecting to the signup page.

{
  "modifications": {
    "logo.href": "https://company.com",
    "banner.href": "https://company.com/products"
  },
  "response": {
    "format": "pdf"
  }
}

Both image elements become clickable in the PDF.

Multi-Page PDFs

Add different links to elements across pages:

{
  "modifications": {
    "page1@cta.href": "https://example.com/page1",
    "page2@cta.href": "https://example.com/page2",
    "page3@cta.href": "https://example.com/page3"
  },
  "response": {
    "format": "pdf"
  }
}

Combining with Content & Styles

You can combine .href with regular parameters and styling:

{
  "modifications": {
    "button": "Learn More",
    "button.href": "https://example.com/learn",
    "button.fontSize": "24px",
    "button.color": "#0066cc",
    "button.backgroundColor": "#f0f0f0"
  },
  "response": {
    "format": "pdf"
  }
}

The button shows "Learn More" text, styled with custom colors and font size, and links to the specified URL.

URL Validation

Orshot validates URLs to ensure they're properly formatted:

✅ Valid URLs:

{
  "link.href": "https://example.com",
  "link.href": "http://example.com",
  "link.href": "https://example.com/path/to/page",
  "link.href": "https://example.com?param=value",
  "link.href": "https://subdomain.example.com"
}

❌ Invalid URLs (ignored):

{
  "link.href": "", // Empty string
  "link.href": "   ", // Whitespace only
  "link.href": "not-a-url", // Missing protocol
  "link.href": "ftp://example.com" // Unsupported protocol
}

Validation Rules

  1. Non-empty - Must contain actual content
  2. Valid Protocol - Must use http:// or https://
  3. Valid Domain - Must have a proper hostname with TLD
  4. Proper Format - Must be parseable as a valid URL

If a URL fails validation:

  • A warning is logged
  • The link is not applied
  • The element remains non-clickable but visually unchanged

Element Type Support

The .href parameter only works with text and image elements:

✅ Supported:

{
  "textElement.href": "https://example.com", // ✓ Text element
  "imageElement.href": "https://example.com" // ✓ Image element
}

❌ Not Supported:

{
  "rectangle.href": "https://example.com", // ✗ Shape element - ignored
  "circle.href": "https://example.com" // ✗ Shape element - ignored
}

Attempting to use .href on unsupported elements will:

  1. Log a warning
  2. Skip the link application
  3. Render the element normally without a link

Security & Safety

XSS Protection

All href values are automatically sanitized to prevent XSS attacks:

// Dangerous characters are escaped
"<script>alert('xss')</script>" → "&lt;script&gt;alert('xss')&lt;/script&gt;"

Error Handling

Malformed URLs are caught and logged without breaking the render:

{
  "link.href": "ht!tp://bad-url" // Invalid - logged and skipped
}

The PDF generates successfully, but this particular link is not applied.

Real-World Examples

Marketing Flyer with CTA

{
  "modifications": {
    "headline": "Limited Time Offer!",
    "cta_text": "Shop Now",
    "cta_text.href": "https://store.example.com/sale",
    "cta_text.fontSize": "28px",
    "cta_text.color": "#ffffff",
    "cta_text.backgroundColor": "#ff6600"
  },
  "response": {
    "format": "pdf",
    "type": "url"
  }
}

Product Catalog

{
  "modifications": {
    "product1_image.href": "https://shop.com/products/item-1",
    "product1_name": "Wireless Headphones",
    "product1_name.href": "https://shop.com/products/item-1",
 
    "product2_image.href": "https://shop.com/products/item-2",
    "product2_name": "Smart Watch",
    "product2_name.href": "https://shop.com/products/item-2"
  },
  "response": {
    "format": "pdf"
  }
}

Multi-Page Report with References

{
  "modifications": {
    "page1@source1.href": "https://research.com/paper/123",
    "page1@source1": "[1] Latest AI Research",
 
    "page2@source2.href": "https://research.com/paper/456",
    "page2@source2": "[2] Machine Learning Advances",
 
    "page3@source3.href": "https://research.com/paper/789",
    "page3@source3": "[3] Neural Networks Study"
  },
  "response": {
    "format": "pdf"
  }
}

Event Invitation

{
  "modifications": {
    "event_name": "Annual Tech Conference 2024",
    "register_button": "Register Now",
    "register_button.href": "https://events.com/register/tech-2024",
    "register_button.fontSize": "32px",
    "register_button.backgroundColor": "#0066cc",
 
    "website_link": "Visit Website",
    "website_link.href": "https://events.com",
    "website_link.fontSize": "16px"
  },
  "response": {
    "format": "pdf",
    "type": "binary"
  }
}

API Integration Examples

REST API

curl -X POST https://api.orshot.com/v1/studio/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id",
    "modifications": {
      "cta_button": "Get Started",
      "cta_button.href": "https://example.com/signup",
      "cta_button.fontSize": "24px",
      "cta_button.color": "#ffffff",
      "cta_button.backgroundColor": "#0066cc"
    },
    "response": {
      "format": "pdf",
      "type": "url"
    }
  }'

Dynamic URL

https://api.orshot.com/v1/studio/dynamic-url/product-card.pdf?
  product_name=Premium%20Headphones&
  product_name.href=https%3A%2F%2Fshop.com%2Fproduct%2F123&
  product_name.fontSize=28px&
  product_image.href=https%3A%2F%2Fshop.com%2Fproduct%2F123

Combining with AI Generation

You can use .href together with .prompt for dynamic linked content:

{
  "modifications": {
    "title.prompt": "Create a call-to-action for a fitness app",
    "title.href": "https://fitness-app.com/download",
    "title.fontSize": "36px",
    "title.color": "#00cc66"
  },
  "response": {
    "format": "pdf"
  }
}

The AI generates appropriate CTA text, which then becomes clickable.

Playground Testing

  1. Open your template in Orshot Studio
  2. Navigate to the Playground tab
  3. Add .href parameters in the Dynamic Parameters section
  4. Set response format to PDF
  5. Generate and download the PDF
  6. Open in a PDF reader to test links

Limitations & Best Practices

Limitations

  1. PDF Only - Links are ignored in PNG, JPEG, and WebP outputs
  2. Element Types - Only text and image elements support links
  3. URL Format - Must be valid http/https URLs
  4. Click Area - Entire element becomes clickable (not individual words)

Best Practices

  1. Always Validate URLs - Use https:// for security
  2. Test Link Functionality - Verify links in actual PDF readers
  3. Use Descriptive Text - Make link purpose clear
  4. Combine with Visual Cues - Use colors/styling to indicate clickability
  5. Track Link Usage - Use URL parameters for analytics: 
    {
  "cta.href": "https://example.com?utm_source=pdf&utm_campaign=summer"
}

Troubleshooting

Issue: Generated PDF doesn't have clickable links

Solutions:

  1. Verify response format is "pdf" (not "png" or "jpeg")
  2. Check URL validation - must be valid http/https URLs
  3. Ensure element type is text or image (not shape)
  4. Test in different PDF readers (some readers have link restrictions)

Issue: Link redirects to unexpected URL

Solutions:

  1. Check for typos in the URL
  2. Ensure URL encoding in dynamic URLs
  3. Verify no conflicting .href parameters
  4. Check for page-specific prefixes in multi-page templates

URL Encoding Issues

Issue: Special characters break the link

Solutions:

// Properly encode URLs with special characters
const encodedUrl = encodeURIComponent(
  "https://example.com?param=value&other=123"
);
 
// Use in modifications
modifications["link.href"] = decodeURIComponent(encodedUrl);

Next Steps

AI Generation with .prompt

Generate dynamic text and images using AI with the .prompt parameter

Video Element Parameters

Control video playback, trim settings, and audio dynamically using video parameters

On this page