Alt Text with .alt

Overview#

The .alt parameter sets the alternate text for an image element. Alt text describes the image for screen readers, and in PDF outputs it's written into the document's accessibility tags, so tagged PDF viewers like Adobe Acrobat read your description instead of showing a generic label.

You can set alt text in two places:

1. In Studio - Select an image layer and fill in the "Alt Text" field in the Image section. This becomes the default for every render.
2. Per render call - Pass parameterID.alt in modifications to set or override the alt text dynamically.

A render-time .alt parameter always wins over the value set in Studio.

Syntax#

parameterID.alt

For multi-page templates:

pageN@parameterID.alt

Basic Usage#

{
  "modifications": {
    "hero_image": "https://example.com/listing-photo.jpg",
    "hero_image.alt": "123 Main St exterior photo"
  },
  "response": {
    "format": "pdf"
  }
}

The image renders as usual, and the PDF's tag layer carries "123 Main St exterior photo" as the image's alternate text.

Multi-Page Templates#

{
  "modifications": {
    "page1@product_shot.alt": "Red running shoe, side view",
    "page2@product_shot.alt": "Red running shoe, top view"
  },
  "response": {
    "format": "pdf"
  }
}

How Defaults Work#

For each image element, the alt text resolves in this order:

1. The .alt modification from the render call, if provided
2. The Alt Text set on the layer in Studio, if any
3. Empty alt text

Empty alt text marks the image as decorative, which tells screen readers to skip it. That's the right behavior for background shapes and ornamental images, so you only need to describe images that carry meaning.

To clear a stored alt for one render, pass an empty string:

{
  "modifications": {
    "logo.alt": ""
  }
}

This overrides the Studio value and marks the image decorative for this render only.

Element Type Support#

.alt works on image elements (including library elements). Passing it for text, shape, or video elements logs a warning and is ignored, and the render continues normally.

Output Format Support#

Checking the Result#

Alt text isn't visible in a normal PDF view. To verify it:

• Open the PDF in Adobe Acrobat and hover the image, or check the Tags panel (View > Show/Hide > Navigation Panes > Accessibility Tags)
• Use a screen reader
• On the command line, tools like pdfinfo -struct-text show the tag content

Real-World Example#

A real estate flyer rendered from a listing feed:

{
  "templateId": "<FLYER_TEMPLATE>",
  "modifications": {
    "address": "123 Main St, Springfield",
    "hero_image": "https://cdn.example.com/listings/1042/front.jpg",
    "hero_image.alt": "Two-story brick house with a covered porch",
    "agent_photo": "https://cdn.example.com/agents/44.jpg",
    "agent_photo.alt": "Agent Sarah Chen"
  },
  "response": {
    "format": "pdf",
    "fileName": "listing-123-main-st"
  }
}

Next Steps#

• Set the document title with PDF Options
• Add Interactive Links with .href
• Explore Dynamic Parameters