# Interactive Links with .href

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

- **URL**: https://orshot.com/docs/dynamic-parameters/link

---

## 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.

## 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```json
{
  "modifications": {
    "cta_button.href": "https://example.com/signup"
  },
  "response": {
    "format": "pdf"
  }
}
```The text element `cta_button` becomes clickable, redirecting to the signup page.

### Image Links```json
{
  "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:```json
{
  "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:```json
{
  "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:**```json
{
  "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):**```json
{
  "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:**```json
{
  "textElement.href": "https://example.com", // ✓ Text element
  "imageElement.href": "https://example.com" // ✓ Image element
}
```❌ **Not Supported:**```json
{
  "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:```javascript
// 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:```json
{
  "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```json
{
  "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```json
{
  "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```json
{
  "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```json
{
  "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```bash
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```markdown
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:```json
{
  "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.

## Testing Links

### 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:
   ```json
   
   ```

## Troubleshooting

### Links Not Working

**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)

### Link Goes to Wrong URL

**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:**```javascript
// 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

- Learn about [AI Content Generation](https://orshot.com/docs/dynamic-parameters/prompt)
- Explore [Dynamic Parameters Introduction](https://orshot.com/docs/dynamic-parameters)
- Check [PDF Options](https://orshot.com/docs/api-reference/pdf-options) for additional PDF settings