Images

The img primitive allows the insertion of images into documents, using the src attribute:

<img src="https://examples.papermill.io/images/logo.jpg"/>

By default, an image will be as large as possible while fitting within the containing block and maintaining the image's aspect ratio. However, the attributes width, height, min-width, and min-height can be used for greater control, similar to block sizing.

Supported Formats

Press supports JPEG, PNG, SVG, and WebP image formats. WebP images are automatically converted to PNG during processing.

SVGs

SVG images can be used with the same <img> element:

<img src="https://examples.papermill.io/images/icon.svg"/>

SVGs are rendered as vector graphics in the output PDF, preserving their resolution independence. This makes them ideal for logos, icons, and diagrams that need to look sharp at any size.

Sizing

SVG dimensions are determined by the width and height attributes on the root <svg> element. If neither is specified, a default width of 100 is used. As with raster images, Press sizing attributes (width, height, min-width, min-height) can be applied to control the rendered size:

<img src="https://examples.papermill.io/images/icon.svg" width="3cm" height="3cm"/>

Using SVGs as Assets

SVGs can be registered in the image asset library just like other image formats:

<assets>
    <images>
        <company-logo>https://examples.papermill.io/images/logo.svg</company-logo>
    </images>
</assets>

And then referenced by name:

<img src="company-logo"/>

Scale

The scale attribute controls how an image fills its container when both width and height are set, similar to CSS object-fit. Available values:

• contain — fits within bounds, preserving aspect ratio (may letterbox)
• cover — covers bounds, preserving aspect ratio (overflows clipped)
• stretch — stretches to exact bounds (may distort)

<img src="https://examples.papermill.io/images/logo.jpg" width="200pt" height="100pt" scale="cover" />

When scale is not specified, the current default behaviour is preserved. See the Scale Mode guide for detailed examples.

Embedded SVGs

If you need to embed raw SVG markup directly in your document instead of referencing an SVG URL, see the Embedded SVGs guide.