imageElementElementElement functions can be customized with set and show rules.
set and show rules.A raster or vector graphic.
You can wrap the image in a figure to give it a number and caption.
Like most elements, images are block-level by default and thus do not
integrate themselves into adjacent paragraphs. To force an image to become
inline, put it into a box.
Example
#figure(
image("molecular.jpg", width: 80%),
caption: [
A step in the molecular testing
pipeline of our lab.
],
)
ParameterParameterParameters are input values for functions. Specify them in parentheses after the function name.
source
Show example
#let original = read("diagram.svg")
#let changed = original.replace(
"#2B80FF", // blue
green.to-hex(),
)
#image(bytes(original))
#image(bytes(changed))
formatSettableSettableSettable parameters can be set using the set rule, changing the default value used thereafter.
set rule, changing the default value used thereafter.The image's format.
By default, the format is detected automatically. Typically, you thus
only need to specify this when providing raw bytes as the
source (even then, Typst will try to figure out the
format automatically, but that's not always possible).
Supported formats are "png", "jpg", "gif", "svg",
"pdf", "webp" as well as raw pixel data.
Note that PDF images are currently not supported when exporting with a specific PDF standard, like PDF/A-3 or PDF/UA-1. In these cases, you can instead use SVGs to embed vector images. Additionally, Typst does not currently support PDFs that are password-protected or have any other kind of encryption.
When providing raw pixel data as the source, you must specify a
dictionary with the following keys as the format:
encoding(str): The encoding of the pixel data. One of:"rgb8"(three 8-bit channels: red, green, blue)"rgba8"(four 8-bit channels: red, green, blue, alpha)"luma8"(one 8-bit channel)"lumaa8"(two 8-bit channels: luma and alpha)
width(int): The pixel width of the image.height(int): The pixel height of the image.
The pixel width multiplied by the height multiplied by the channel count
for the specified encoding must then match the source data.
Available string values:
pngRaster format for illustrations and transparent graphics.
jpgLossy raster format suitable for photos.
gifRaster format that is typically used for short animated clips. Typst can load GIFs, but they will become static.
webpRaster format that supports both lossy and lossless compression.
svgThe vector graphics format of the web.
pdfHigh-fidelity document and graphics format, with focus on exact reproduction in print.
Default value: auto
Show example
#image(
read(
"tetrahedron.svg",
encoding: none,
),
format: "svg",
width: 2cm,
)
#image(
bytes(range(16).map(x => x * 16)),
format: (
encoding: "luma8",
width: 4,
height: 4,
),
width: 2cm,
)
width
The width of the image.
Default value: auto
height
The height of the image.
Default value: auto
alt
A text describing the image.
Default value: none
pageSettableSettableSettable parameters can be set using the set rule, changing the default value used thereafter.
set rule, changing the default value used thereafter.The page number that should be embedded as an image. This attribute only has an effect for PDF files.
Default value: 1
fitSettableSettableSettable parameters can be set using the set rule, changing the default value used thereafter.
set rule, changing the default value used thereafter.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.
Available string values:
coverThe image should completely cover the area (preserves aspect ratio by cropping the image only horizontally or vertically). This is the default.
containThe image should be fully contained in the area (preserves aspect ratio; doesn't crop the image; one dimension can be narrower than specified).
stretchThe 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 value: "cover"
Show 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")
scaling
A hint to viewers how they should scale the image.
When set to auto, the default is left up to the viewer. For PNG
export, Typst will default to smooth scaling, like most PDF and SVG
viewers.
Note: The exact look may differ across PDF viewers.
Available string values:
smoothScale with a smoothing algorithm such as bilinear interpolation.
pixelatedScale with nearest neighbor or a similar algorithm to preserve the pixelated look of the image.
Default value: auto
icc
An ICC profile for the image.
ICC profiles define how to interpret the colors in an image. When set
to auto, Typst will try to extract an ICC profile from the image.
Default value: auto
DefinitionDefinitionThese functions and types can have related definitions. To access a definition, specify the name of the function or type, followed by the definition name separated by a period.
decode
Decode a raster or vector graphic from bytes or a string.
data
The data to decode as an image. Can be a string for SVGs.
format
The image's format. Detected automatically by default.
Available string values:
pngRaster format for illustrations and transparent graphics.
jpgLossy raster format suitable for photos.
gifRaster format that is typically used for short animated clips. Typst can load GIFs, but they will become static.
webpRaster format that supports both lossy and lossless compression.
svgThe vector graphics format of the web.
pdfHigh-fidelity document and graphics format, with focus on exact reproduction in print.
fit
How the image should adjust itself to a given area.
Available string values:
coverThe image should completely cover the area (preserves aspect ratio by cropping the image only horizontally or vertically). This is the default.
containThe image should be fully contained in the area (preserves aspect ratio; doesn't crop the image; one dimension can be narrower than specified).
stretchThe 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).