Skip to content

type: image ​

This page renders docs/engine/image.md.Generated here: the sidebar, the tables and the demo below.

View source

An image item. The source comes from src (template-time: a path under the assets directory, a data: URI, or inline SVG markup) or data (a params-bound value, subject to the host's asset policy) — exactly one must be set. A data binding reads only its key: a format or placeholder on it is accepted and has no effect. box.w/box.h are required to reserve space (layout never sizes from image pixels).

Syntax ​

yaml
- type: image
  box: { w: 120, h: 40 }
  src: logo.svg                  # path under the assets root (--assets-dir,
                                 # default: the template file's directory)
  # src: "data:image/png;base64,…"
  # src: "<svg …>…</svg>"        # inline SVG
  # data: { key: product.image } # params-bound (policy-gated)
  fit: contain                   # contain | cover | stretch | none
  style: { backgroundColor: "#f2f2f2", borderWidth: 0.5 }

Keys ​

KeyTypeDefaultDescription
srcstringBundled path, data: URI, or inline SVG. A path resolves against the assets root — --assets-dir, defaulting to the template file's directory (so examples/business/receipt-ja/templates.yml can say src: assets/logo.svg); paths escaping the root are rejected (asset_traversal). Remote URLs are recognized and rejected (remote_asset_unsupported — the render path has no network I/O, and unlike a font there is no sha256 pin that would make fetching an image deterministic).
data{ key }Dynamic source from params; the host's asset policy (open vs bundled-only, per-item allow/deny via CLI --allow/deny-dynamic-image) gates it.
bindingsmap of name → bindingNamed declarations for the {name} interpolations in this item's link.url (data-binding.md).
fitcontain | cover | stretch | nonecontainCSS object-fit, all centered. contain preserves aspect ratio inside the box (letterbox); cover preserves aspect ratio filling the box and crops the overflow; stretch fills the box exactly (distorting); none draws at the asset's intrinsic size (raster px at 72dpi / SVG viewBox units). cover/none clip anything past the content box — and an SVG clips under every fit (see below).
box.w / box.hLengthrequiredThe fit box (inset by padding).
style / styleNamesDecoration (backgroundColor, borderWidth/borderColor) plus opacity (see below); text properties are unused.
link{ url }Hyperlink over the draw box. See link.md.

The box always holds ​

An image never paints outside its content box. For a raster that falls out of the fit math — the pixels are exactly their own rect — so only cover/none need the crop. An SVG is different: its intrinsic size is the viewBox, but nothing stops a path from being drawn outside it, so the fitted rect is not the painted rect. The viewBox is the viewport and a viewport clips (the outermost <svg> carries overflow: hidden), so every SVG is clipped to the content box under every fit — contain and stretch included.

This matters when the asset is not yours: without it, one hostile or merely sloppy SVG could paint over the whole page. If your own artwork looks cropped, its shapes extend past the viewBox — widen the viewBox rather than expecting the overflow to draw.

Opacity ​

style: { opacity: 0.5 } applies a whole-image paint alpha (0..=1). Both backends composite the raster or vector image as one group, so a partly-transparent image reads as a single unit (overlapping SVG paths do not double-blend at their seams). Out-of-range or non-finite values warn invalid_opacity and draw opaque.

Formats ​

  • Raster: PNG, JPEG, GIF, WebP — sniffed by magic bytes, header dimensions validated, size-capped by the asset policy. A GIF is drawn from its first frame, so that frame must fill the GIF's logical screen (same size, placed at the top-left corner); a GIF whose first frame is smaller, larger or offset is refused (invalid_image_asset for a template src:, invalid_image_data for a params value).
  • SVG: a deliberate subset parser (paths, basic shapes, groups, affine transforms, presentation attributes; node/depth caps). Text inside SVG is not rendered. Unsupported constructs warn svg_unsupported.
    • The viewBox (or width/height) must be between 0.001 and 1,000,000 units on each side, with its origin within ±1,000,000,000; otherwise the SVG is refused (invalid_image_asset for a template src:, invalid_image_data for a params value).
    • The coordinate range: after the transforms apply, a coordinate may lie at most 1000 viewBox widths (x) or heights (y) from the viewBox origin. A shape with a coordinate farther out, or with an infinite or NaN one, is not drawn. A stroke wider than 1000 times the viewBox's smaller side is not drawn (the shape's fill still is), and a gradient whose coordinates, radius or transform entries exceed twice the range is not used. Each warns svg_unsupported. The image is clipped to its viewBox, so a shape lying wholly that far out was invisible anyway; only a shape that crosses the viewBox and also reaches past the range has a visible part left undrawn — a shape just past the viewBox's edge is drawn and clipped as usual.
    • PNG previews skip a shape that reaches more than 16,777,216 px from the page's corner, without a diagnostic; with the coordinate range above, that happens only for an image drawn more than about 16,800 px wide or tall (about 5,600 px with a stroke as wide as the stroke limit allows).
    • Arcs (A/a in path data) are flattened to at most eleven curve segments each, accurate to 0.1 units or a millionth of the radius, whichever is larger.
    • Gradients: <linearGradient> / <radialGradient> fills are supported — <stop> colors/opacity (including via style="…"), both gradientUnits (userSpaceOnUse and the objectBoundingBox default), gradientTransform, spreadMethod (pad/reflect/repeat), radial focal point, and one-level href/xlink:href stop inheritance (the Inkscape/Illustrator stop-holder pattern). Gradient strokes are not yet drawn (they warn and fall back to the inherited solid stroke); an undefined url(#id) reference warns and leaves the shape unpainted. Both the PDF and PNG backends draw gradients identically.

In repeat / repeat_flow cells ​

Images work inside repeat cells, repeat_flow cards, and a table column's cell:. A static src: is one shared asset drawn once per element; a data: binding is element-scoped — its key is a field of the bound array element and each element loads its own asset (dyn:<array>[<i>].<key>), under the same per-element load cap as table image columns (cell_image_assets_capped).

A data: binding with scope: document is the third case: the key reads top-level params, so the cell draws ONE shared asset (dyn:<key>, loaded once and uncounted against the per-element cap) — the shop logo on every ticket, without hard-coding a src: path. The host asset policy gates dynamic cell images by the image item's id.

Limitations ​

  • box.w/box.h are required — layout reserves the space before it knows the source (image_missing_size).
  • Exactly one of src/data (image_source_conflict / image_source_missing).
  • No network at render time: a remote URL source is refused (remote_asset_unsupported).
  • A bundled path must stay under the assets root (missing_asset, assets_root_missing, asset_traversal).
  • SVG is a SUBSET parser; constructs outside it leave the shape unpainted (svg_unsupported).
  • Per-element cell images share a 1000-load cap across table columns and repeat/repeat_flow cells (cell_image_assets_capped), and a params-bound image can be refused by the host's asset policy (dynamic_image_denied).

Diagnostics ​

CodeMeaning
image_missing_sizebox.w/box.h absent
image_source_conflict / image_source_missingboth / neither of src+data set — a validation error, so the document does not render
empty_image_itemneither set, reported by layout itself; only a caller that lays out without validating sees it, since the render pipelines refuse the document with image_source_missing first
missing_asset / assets_root_missing / asset_traversalbundled path problems (absent, no root, escapes the root); missing_asset also follows a data image whose value never loaded
missing_dataa data image's key is empty or absent from params (warning, with missing_asset; nothing is drawn)
invalid_image_data / invalid_image_assetundecodable or unresolvable sources, including a params value that is not a string
remote_asset_unsupportedremote URL source; rejected
dynamic_image_deniedparams-bound image blocked by the asset policy
svg_unsupportedSVG constructs outside the subset, and coordinates, stroke widths or gradients past the coordinate range
length_out_of_rangea fit: none or cover image would be drawn wider or taller than 1,000,000 pt; it is drawn at the contain size instead
cell_image_assets_cappedper-element cell images (table columns + repeat cells) exceed the shared load cap; the rest are skipped
invalid_opacityout-of-range / non-finite opacity; draws opaque

Capability keys: image, image.fit.cover_none (the cover / none fit modes), image.svg.gradient (gradient fills in the SVG subset — gate gradient previews on it; older engines leave gradient-filled shapes unpainted with an svg_unsupported warning), image.cells (images inside repeat/repeat_flow cells — older engines warn+skip there), and image.opacity (whole-image group alpha; older engines ignore it).

See also ​

  • link.md — link: { url } over the image
  • qr_code.md — vector codes with no asset pipeline