{"route":"/en-US-v0.14.1/reference/visualize/image/","title":"Image","description":"Documentation for the `image` function.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"example","name":"Example","children":[]},{"id":"parameters","name":"Parameters","children":[{"id":"parameters-source","name":"source","children":[]},{"id":"parameters-format","name":"format","children":[]},{"id":"parameters-width","name":"width","children":[]},{"id":"parameters-height","name":"height","children":[]},{"id":"parameters-alt","name":"alt","children":[]},{"id":"parameters-page","name":"page","children":[]},{"id":"parameters-fit","name":"fit","children":[]},{"id":"parameters-scaling","name":"scaling","children":[]},{"id":"parameters-icc","name":"icc","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-decode","name":"Decode Image","children":[{"id":"definitions-decode-data","name":"data","children":[]},{"id":"definitions-decode-format","name":"format","children":[]},{"id":"definitions-decode-width","name":"width","children":[]},{"id":"definitions-decode-height","name":"height","children":[]},{"id":"definitions-decode-alt","name":"alt","children":[]},{"id":"definitions-decode-fit","name":"fit","children":[]},{"id":"definitions-decode-scaling","name":"scaling","children":[]}]}]}],"body":{"kind":"func","content":{"path":[],"name":"image","title":"Image","keywords":[],"oneliner":"A raster or vector graphic.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

A raster or vector graphic.

\n

You can wrap the image in a figure to give it a number and caption.

\n

Like most elements, images are block-level by default and thus do not\nintegrate themselves into adjacent paragraphs. To force an image to become\ninline, put it into a box.

\n

Example

\n
#figure(\n  image("molecular.jpg", width: 80%),\n  caption: [\n    A step in the molecular testing\n    pipeline of our lab.\n  ],\n)\n
\"Preview\"
"}],"self":false,"params":[{"name":"source","details":[{"kind":"html","content":"

A path to an image file or raw bytes making up an\nimage in one of the supported formats.

\n

Bytes can be used to specify raw pixel data in a row-major,\nleft-to-right, top-to-bottom format.

"},{"kind":"example","content":{"body":"
#let original = read("diagram.svg")\n#let changed = original.replace(\n  "#2B80FF", // blue\n  green.to-hex(),\n)\n\n#image(bytes(original))\n#image(bytes(changed))\n
\"Preview\"
","title":null}}],"types":["str","bytes"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"format","details":[{"kind":"html","content":"

The image's format.

\n

By default, the format is detected automatically. Typically, you thus\nonly need to specify this when providing raw bytes as the\nsource (even then, Typst will try to figure out the\nformat automatically, but that's not always possible).

\n

Supported formats are "png", "jpg", "gif", "svg",\n"pdf", "webp" as well as raw pixel data.

\n

Note that several restrictions apply when using PDF files as images:

\n\n

When providing raw pixel data as the source, you must specify a\ndictionary with the following keys as the format:

\n\n

The pixel width multiplied by the height multiplied by the channel count\nfor the specified encoding must then match the source data.

"},{"kind":"example","content":{"body":"
#image(\n  read(\n    "tetrahedron.svg",\n    encoding: none,\n  ),\n  format: "svg",\n  width: 2cm,\n)\n\n#image(\n  bytes(range(16).map(x => x * 16)),\n  format: (\n    encoding: "luma8",\n    width: 4,\n    height: 4,\n  ),\n  width: 2cm,\n)\n
\"Preview\"
","title":null}}],"types":["auto","str","dictionary"],"strings":[{"string":"png","details":"

Raster format for illustrations and transparent graphics.

"},{"string":"jpg","details":"

Lossy raster format suitable for photos.

"},{"string":"gif","details":"

Raster format that is typically used for short animated clips. Typst can\nload GIFs, but they will become static.

"},{"string":"webp","details":"

Raster format that supports both lossy and lossless compression.

"},{"string":"svg","details":"

The vector graphics format of the web.

"},{"string":"pdf","details":"

High-fidelity document and graphics format, with focus on exact\nreproduction in print.

"}],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"width","details":[{"kind":"html","content":"

The width of the image.

"}],"types":["auto","relative"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"height","details":[{"kind":"html","content":"

The height of the image.

"}],"types":["auto","relative","fraction"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"alt","details":[{"kind":"html","content":"

An alternative description of the image.

\n

This text is used by Assistive Technology (AT) like screen readers to\ndescribe the image to users with visual impairments.

\n

When the image is wrapped in a figure, use this parameter\nrather than the figure's alt parameter to describe the\nimage. The only exception to this rule is when the image and the other\ncontents in the figure form a single semantic unit. In this case, use\nthe figure's alt parameter to describe the entire composition and do\nnot use this parameter.

\n

You can learn how to write good alternative descriptions in the\nAccessibility Guide.

"}],"types":["none","str"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"page","details":[{"kind":"html","content":"

The page number that should be embedded as an image. This attribute only\nhas an effect for PDF files.

"}],"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"fit","details":[{"kind":"html","content":"

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

"},{"kind":"example","content":{"body":"
#set page(width: 300pt, height: 50pt, margin: 10pt)\n#image("tiger.jpg", width: 100%, fit: "cover")\n#image("tiger.jpg", width: 100%, fit: "contain")\n#image("tiger.jpg", width: 100%, fit: "stretch")\n
\"Preview\"Preview\"Preview
","title":null}}],"types":["str"],"strings":[{"string":"cover","details":"

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

"},{"string":"contain","details":"

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

"},{"string":"stretch","details":"

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

"}],"default":""cover"","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"scaling","details":[{"kind":"html","content":"

A hint to viewers how they should scale the image.

\n

When set to auto, the default is left up to the viewer. For PNG\nexport, Typst will default to smooth scaling, like most PDF and SVG\nviewers.

\n

Note: The exact look may differ across PDF viewers.

"}],"types":["auto","str"],"strings":[{"string":"smooth","details":"

Scale with a smoothing algorithm such as bilinear interpolation.

"},{"string":"pixelated","details":"

Scale with nearest neighbor or a similar algorithm to preserve the\npixelated look of the image.

"}],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"icc","details":[{"kind":"html","content":"

An ICC profile for the image.

\n

ICC profiles define how to interpret the colors in an image. When set\nto auto, Typst will try to extract an ICC profile from the image.

"}],"types":["auto","str","bytes"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[{"path":["image"],"name":"decode","title":"Decode Image","keywords":[],"oneliner":"Decode a raster or vector graphic from bytes or a string.","element":false,"contextual":false,"deprecationMessage":"`image.decode` is deprecated, directly pass bytes to `image` instead","deprecationUntil":"0.15.0","details":[{"kind":"html","content":"

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

"}],"self":false,"params":[{"name":"data","details":[{"kind":"html","content":"

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

"}],"types":["str","bytes"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"format","details":[{"kind":"html","content":"

The image's format. Detected automatically by default.

"}],"types":["auto","str","dictionary"],"strings":[{"string":"png","details":"

Raster format for illustrations and transparent graphics.

"},{"string":"jpg","details":"

Lossy raster format suitable for photos.

"},{"string":"gif","details":"

Raster format that is typically used for short animated clips. Typst can\nload GIFs, but they will become static.

"},{"string":"webp","details":"

Raster format that supports both lossy and lossless compression.

"},{"string":"svg","details":"

The vector graphics format of the web.

"},{"string":"pdf","details":"

High-fidelity document and graphics format, with focus on exact\nreproduction in print.

"}],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"width","details":[{"kind":"html","content":"

The width of the image.

"}],"types":["auto","relative"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"height","details":[{"kind":"html","content":"

The height of the image.

"}],"types":["auto","relative","fraction"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"alt","details":[{"kind":"html","content":"

A text describing the image.

"}],"types":["none","str"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"fit","details":[{"kind":"html","content":"

How the image should adjust itself to a given area.

"}],"types":["str"],"strings":[{"string":"cover","details":"

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

"},{"string":"contain","details":"

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

"},{"string":"stretch","details":"

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

"}],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"scaling","details":[{"kind":"html","content":"

A hint to viewers how they should scale the image.

"}],"types":["auto","str"],"strings":[{"string":"smooth","details":"

Scale with a smoothing algorithm such as bilinear interpolation.

"},{"string":"pixelated","details":"

Scale with nearest neighbor or a similar algorithm to preserve the\npixelated look of the image.

"}],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["content"],"scope":[]}]}}}