Image

Embed raster images.

Props

Prop	Type	Required	Default	Description
src	Uint8Array | string	Yes	—	Image bytes, or a data: URI. A URL/path string is passed through to the SVG href but is not fetched — raster output omits it and a IMAGE_SRC_NOT_EMBEDDED warning is emitted. Read the file yourself and pass the bytes.
mediaType	"image/png" | "image/jpeg" | "image/svg+xml"		—	Required when src is Uint8Array
width	number	Yes	—	Width in px
height	number	Yes	—	Height in px
objectFit	"fill" | "contain" | "cover"		"fill"	Image fitting mode
objectPosition	string		"center"	Image position within the box (e.g. "top", "center")
borderRadius	number | [number, number, number, number]		—	Border radius for rounded image clipping
opacity	number		—	Opacity (0–1)
zIndex	number		—	Sibling-local paint order (integer; higher paints later)
meta	Record<string, string>		—	Metadata emitted as data-boundsvg-meta-* attributes and into the layered manifest (max 16 keys, [a-z][a-z0-9-]{0,31} keys, 256-char values)
transform	Transform2D		—	Static post-layout paint transform
animate	AnimationSpec		—	Declarative opacity/transform track; see Animation

Flex Item

Prop	Type	Default	Description
flexGrow	number	0	Flex grow factor
flexShrink	number	1	Flex shrink factor
flexBasis	number | "auto"	"auto"	Flex basis
alignSelf	"auto" | "start" | "center" | "end" | "stretch"	"auto"	Self alignment

Grid Item

Prop	Type	Description
gridColumn	string	Grid column placement (e.g. "1 / 3")
gridRow	string	Grid row placement (e.g. "1 / 2")

Positioning

Prop	Type	Default	Description
position	"relative" | "absolute"	"relative"	Positioning mode
top	number	—	Top offset in px
right	number	—	Right offset in px
bottom	number	—	Bottom offset in px
left	number	—	Left offset in px

Box Model

Prop	Type	Description
margin	number | [number, number, number, number]	Margin (uniform or [top, right, bottom, left])

Event / Identity

Prop	Type	Description
onClick	string	Click handler reference
onDoubleClick	string	Double-click handler reference
onContextMenu	string	Context menu handler reference
onPointerMove	string	Pointer move handler reference
onPointerEnter	string	Pointer enter handler reference
onPointerLeave	string	Pointer leave handler reference
id	string	Stable NodeId for hit-testing
layer	string	Layer id for Layered Export

All 21 event handler props are supported. See Event Handlers for the full list.

objectFit Mapping

Value	SVG preserveAspectRatio	Description
"fill"	"none"	Stretch to fill the box
"contain"	"xMidYMid meet"	Scale to fit, maintaining aspect ratio
"cover"	"xMidYMid slice"	Scale to cover, cropping as needed

Example

import fs from "node:fs";

const logo = fs.readFileSync("logo.png");

<Image
  src={logo}
  mediaType="image/png"
  width={200}
  height={100}
  objectFit="contain"
/>;

Fetching remote images

The render pipeline never fetches URLs. To embed a remote image, load the bytes first — createBrowserImageLoader (@boundsvg/browser) caches results and merges concurrent requests for the same URL:

import { createBrowserImageLoader } from "@boundsvg/browser";

const imageLoader = createBrowserImageLoader();
const loaded = await imageLoader.load("https://example.com/logo.png");
// The loaded mediaType is a plain string — narrow it to the union
// Image accepts before passing it through.
if (loaded.mediaType !== "image/png") {
  throw new Error(`unexpected media type: ${loaded.mediaType}`);
}

<Image src={loaded.data} mediaType="image/png" width={200} height={100} />;

In Node.js or custom runtimes, use createImageLoader (@boundsvg/core) with your own fetch implementation. See the core API reference.

Data URL

<Canvas width={300} height={220} background="#0f172a">
  <Flex
    width={300}
    height={220}
    padding={16}
    justifyContent="center"
    alignItems="center"
  >
    <Image
      src="data:image/svg+xml;utf8,<svg ...>...</svg>"
      width={240}
      height={180}
      objectFit="contain"
    />
  </Flex>
</Canvas>

Generated SVG

<svg xmlns="http://www.w3.org/2000/svg" data-boundsvg-node-id="auto:0" viewBox="0 0 300 220" width="300" height="220">
  <rect x="0" y="0" width="300" height="220" fill="#0f172a"/>
  <g data-boundsvg-node-id="auto:0.0">
    <g data-boundsvg-node-id="auto:0.0.0">
      <image data-boundsvg-node-id="auto:0.0.0" href="data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22240%22%20height%3D%22180%22%20viewBox%3D%220%200%20240%20180%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22g%22%20x1%3D%220%22%20y1%3D%220%22%20x2%3D%221%22%20y2%3D%221%22%3E%3Cstop%20offset%3D%220%25%22%20stop-color%3D%22%232a2a72%22%2F%3E%3Cstop%20offset%3D%22100%25%22%20stop-color%3D%22%23009ffd%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%22240%22%20height%3D%22180%22%20fill%3D%22url(%23g)%22%2F%3E%3Ccircle%20cx%3D%22188%22%20cy%3D%2242%22%20r%3D%2222%22%20fill%3D%22%23ffd166%22%20opacity%3D%220.85%22%2F%3E%3Crect%20x%3D%220%22%20y%3D%22120%22%20width%3D%22240%22%20height%3D%2260%22%20fill%3D%22%23111827%22%20opacity%3D%220.5%22%2F%3E%3C%2Fsvg%3E" x="30" y="20" width="240" height="180" preserveAspectRatio="xMidYMid meet"/>
    </g>
  </g>
</svg>

INFO

If the image fails to load, a placeholder rectangle is rendered (recoverable error).