Documentation

imageElement
Question mark

A raster or vector graphic.

Supported formats are PNG, JPEG, GIF and SVG.

Note: Work on SVG export is ongoing and there might be visual inaccuracies in the resulting PDF. Make sure to double-check embedded SVG images. If you have an issue, also feel free to report it on GitHub.

Example

#figure(
  image("molecular.jpg", width: 80%),
  caption: [
    A step in the molecular testing
    pipeline of our lab.
  ],
)
Preview

Parameters
Question mark

path
str
RequiredPositional
Question mark

Path to an image file.

format
auto or str
Settable
Question mark

The image's format. Detected automatically by default.

VariantDetails
"png"

Raster format for illustrations and transparent graphics.

"jpg"

Lossy raster format suitable for photos.

"gif"

Raster format that is typically used for short animated clips.

"svg"

The vector graphics format of the web.

Default: auto

width
auto or relative
Settable
Question mark

The width of the image.

Default: auto

height
auto or relative
Settable
Question mark

The height of the image.

Default: auto

alt
none or str
Settable
Question mark

A text describing the image.

Default: none

fit
str
Settable
Question mark

How the image should adjust itself to a given area (the area is defined by the width and height fields). Note that fit doesn't visually change anything if the area's aspect ratio is the same as the image's one.

VariantDetails
"cover"

The image should completely cover the area (preserves aspect ratio by cropping the image only horizontally or vertically). This is the default.

"contain"

The image should be fully contained in the area (preserves aspect ratio; doesn't crop the image; one dimension can be narrower than specified).

"stretch"

The image should be stretched so that it exactly fills the area, even if this means that the image will be distorted (doesn't preserve aspect ratio and doesn't crop the image).

Default: "cover"

View example
#set page(width: 300pt, height: 50pt, margin: 10pt)
#image("tiger.jpg", width: 100%, fit: "cover")
#image("tiger.jpg", width: 100%, fit: "contain")
#image("tiger.jpg", width: 100%, fit: "stretch")
Preview Preview Preview

Definitions
Question mark

decode

Decode a raster or vector graphic from bytes or a string.

#let original = read("diagram.svg")
#let changed = original.replace(
  "#2B80FF", // blue
  green.to-hex(),
)

#image.decode(original)
#image.decode(changed)
Preview

data
str or bytes
RequiredPositional
Question mark

The data to decode as an image. Can be a string for SVGs.

format

The image's format. Detected automatically by default.

VariantDetails
"png"

Raster format for illustrations and transparent graphics.

"jpg"

Lossy raster format suitable for photos.

"gif"

Raster format that is typically used for short animated clips.

"svg"

The vector graphics format of the web.

width

The width of the image.

height

The height of the image.

alt

A text describing the image.

fit

How the image should adjust itself to a given area.

VariantDetails
"cover"

The image should completely cover the area (preserves aspect ratio by cropping the image only horizontally or vertically). This is the default.

"contain"

The image should be fully contained in the area (preserves aspect ratio; doesn't crop the image; one dimension can be narrower than specified).

"stretch"

The image should be stretched so that it exactly fills the area, even if this means that the image will be distorted (doesn't preserve aspect ratio and doesn't crop the image).