Images

Press renders images from URLs, asset libraries, or base64-encoded data. Images can be placed as standalone blocks, inline within text, or as full-page backgrounds.

Basic Usage

<img src="https://example.com/images/photo.jpg" />

Default Sizing

By default with no width or height specified, an image fills the available width. If using all available width would make the image taller than the available height, it uses all available height instead, maintaining aspect ratio.

Explicit Sizing

Set width, height, or both:

<img src="https://example.com/logo.png" width="120pt" />
<img src="https://example.com/banner.jpg" height="200pt" />
<img src="https://example.com/icon.png" width="48pt" height="48pt" />

Size Constraints

Use max-width and max-height to set upper bounds while preserving aspect ratio:

<img src="https://example.com/photo.jpg" max-width="300pt" max-height="200pt" />

The image scales down to fit within the constraints without distortion.

Scale Mode

The scale attribute controls how an image fills its container when both width and height are set. It works like CSS object-fit:

Value	Behavior
contain	Fits within bounds preserving aspect ratio (may letterbox)
cover	Covers bounds preserving aspect ratio (overflows clipped)
stretch	Stretches to exact bounds (may distort)

When scale is not set, images use their current default behavior.

Contain

Scales the image to fit entirely within the given dimensions. If the aspect ratio doesn't match, empty space appears around the image:

<img src="https://example.com/photo.jpg" width="200pt" height="100pt" scale="contain" />

Cover

Scales the image to completely fill the given dimensions, cropping any overflow. The image is centred within the bounds:

<img src="https://example.com/photo.jpg" width="200pt" height="100pt" scale="cover" />

This is useful for hero images, thumbnails, or any case where the image should fill a fixed-size area without distortion.

Stretch

Stretches the image to exactly match the given dimensions, ignoring aspect ratio:

<img src="https://example.com/photo.jpg" width="200pt" height="100pt" scale="stretch" />

Scale with Border Radius

Scale modes compose with border-radius for rounded or circular images:

<img src="https://example.com/avatar.jpg"
     width="80pt" height="80pt"
     scale="cover" border-radius="40pt" />

Images from Asset Libraries

Define named images in <assets> and reference them by name:

<assets>
  <images>
    <logo>https://example.com/images/company-logo.png</logo>
    <banner>https://example.com/images/header-banner.jpg</banner>
    <icon-phone>https://example.com/images/phone-icon.png</icon-phone>
  </images>
</assets>

Then use the name directly in src:

<img src="logo" max-width="120pt" />
<img src="banner" width="100%" />

Images from Data

Bind image sources to data:

<img src="{{ data.author-photo }}" max-height="150pt" />
<img show-if="data.graphic" src="{{ data.graphic }}" width="100%" />

Full-Page Background Images

Use absolute positioning to place an image behind all other content:

<page>
  <img top="0" left="0" width="100%" height="100%"
       src="https://example.com/images/background.jpg" />
  <frame padding="2cm">
    <h1 font-color="white">Cover Page Title</h1>
  </frame>
</page>

The image is positioned at the top-left corner and stretched to fill the page. Content after the image is rendered over the top of the image.

Improving Text Over Images

Text-shadow

Adding a shadow of the opposite color to you heading can increase text readability against a background image:

<page>
  <img top="0" left="0" width="100%" height="100%"
       src="https://example.com/images/landscape.jpg" />
  <frame padding="3cm" v-align="bottom">
    <h1 font-color="white" text-shadow="0.5pt black" font-size="36pt">Annual Report 2026</h1>
  </frame>
</page>

Semi-Transparent Overlays

Layer a coloured frame over a background image can also produce readable text:

<page>
  <img top="0" left="0" width="100%" height="100%"
       src="https://example.com/images/landscape.jpg" />
  <frame top="0" left="0" width="100%" height="100%"
         background-color="rgba(0, 0, 0, 0.4)" />
  <frame padding="3cm" v-align="bottom">
    <h1 font-color="white" font-size="36pt">Annual Report 2026</h1>
  </frame>
</page>

Transparency

For images with transparent regions (PNGs), add transparency="true":

<img src="logo" transparency="true" width="200pt" />

Alternately, you can set the background color of the image which will fill all transparent pixels.

Inline Images

Images inside a <p> or alongside text are rendered inline:

<p>
  Contact us at
  <img src="icon-phone" width="12pt" height="12pt" /> +44 7700 123456
</p>

Embedded SVGs

In addition to referencing SVG files via <img src="...">, you can embed raw SVG markup directly in your Press document using the <svg> element. This is useful when you want to generate or manipulate SVG content dynamically as part of your template. You'll need to obey the Papermill dimension system for width and height on the SVG tag itself but everything inside has no units as it is in viewBox space. The viewbox is automatically calculated if it is missing..

<svg xmlns="http://www.w3.org/2000/svg" width="200pt" height="100pt" viewBox="0 0 200 100">
  <rect width="200" height="100" fill="#4376ba" rx="8" />
  <text x="100" y="55" text-anchor="middle" fill="white" font-size="18">Hello SVG</text>
</svg>

The <svg> element is treated as a block and supports standard block attributes such as space-before-desired and space-after-desired.

Sizing

Dimensions are read from the width and height attributes on the root <svg> element. If only one dimension is specified, the other is inferred to preserve aspect ratio. If a dimension is missing, the viewBox is used to attempt to scale the SVG correctly into pts.

The SVG automatically scales down to fit within its containing block while preserving aspect ratio. You can also use percentage values to size relative to the available space:

<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="200pt" viewBox="0 0 400 200">
  <rect width="400" height="200" fill="#f3f4f6" />
</svg>

Data-Driven SVGs

Combine embedded SVGs with data expressions to create dynamic graphics:

<svg xmlns="http://www.w3.org/2000/svg" width="200" height="30" viewBox="0 0 200 30">
  <rect width="{{ data.progress }}%" height="30" fill="#059669" rx="4" />
  <rect width="100%" height="30" fill="none" stroke="#e5e7eb" rx="4" />
</svg>

When to Use Embedded SVGs vs <img>

Approach	Best For
<img src="...svg">	Static SVG files hosted at a URL or registered as assets
<svg>	SVGs generated dynamically with data expressions, or SVGs authored directly in the template

Example: A Property Card

<frame break="never" border-weight="0.5pt" border-color="#e5e7eb" border-radius="6pt">
  <img src="{{ property.image }}" width="100%" max-height="200pt" />
  <frame padding="12pt">
    <frame font-size="14pt" font-style="bold">{{ property.address }}</frame>
    <frame font-size="11pt" font-color="#4b5563" space-after-desired="8pt">
      {{ property.bedrooms }} bed | {{ property.bathrooms }} bath | {{ property.sqft }} sq ft
    </frame>
    <frame font-size="16pt" font-style="bold" font-color="#059669">
      {{ property.price }}
    </frame>
  </frame>
</frame>