An SVG diagram often needs an element that is not drawn as a vector: a partner's logo supplied as a PNG, a screenshot, or an icon that already exists as its own SVG file. Redrawing that visual by hand, point by point, would be both slow and pointless.
The <image> element lets you embed that external file, PNG, JPEG, GIF, WebP, or even another SVG, directly inside the canvas, positioned and resized with the same precision as any neighbouring vector shape.
Definition
<image> displays a bitmap file or an external SVG document inside an SVG, referenced through the href attribute (or the older xlink:href on legacy browsers). Unlike a shape drawn from points, it is not built from geometric coordinates but from the pixels or content of the referenced file, placed inside a rectangle defined by x, y, width and height.
Main attributes
- href: the URL, or the base64 data, of the file to display.
- x, y, width, height: the rectangular area the image is placed into.
- preserveAspectRatio: controls what happens when the file's proportions do not exactly match the
x/y/width/heightrectangle. The default valuexMidYMid meetresizes the image while keeping its proportions and centers it, leaving empty space if needed.xMidYMid slicefills the whole rectangle by cropping the overflow, andnonestretches the image to fit the frame exactly.
A concrete example
A bitmap logo placed next to a vector frame drawn with a rectangle:
<svg viewBox="0 0 300 120" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" width="300" height="120" rx="12" fill="#0f172a" />
<image href="partner-logo.png" x="20" y="20" width="80" height="80" preserveAspectRatio="xMidYMid meet" />
<text x="120" y="65" fill="#ffffff" font-size="18">Official partner</text>
</svg>The logo keeps its original proportions thanks to preserveAspectRatio, even though the frame that hosts it does not share the exact same ratio as the source PNG file.
Difference from the HTML <img> tag
Both display an image, but not in the same world. The HTML <img> tag lives in the normal flow of a web page, with its own attributes like alt, loading or srcset. <image> only lives inside an SVG document, positioned by geometric coordinates exactly like a neighbouring shape, and can be transformed, clipped or animated with the same tools as the rest of the drawing, something a plain HTML <img> cannot do natively.
| Aspect | <img> in HTML | <image> in SVG |
|---|---|---|
| Context | Anywhere in an HTML page | Only inside an SVG document |
| Source attribute | src | href |
| Alternative text | Native alt attribute | Goes through a <desc> or an ARIA attribute |
| Transformations | Requires CSS (transform, clip-path...) | Native, with the same attributes as other shapes |
A classic trap
<image> does not let you change its colors or content from the parent document: unlike a <use> referencing an internal <symbol>, which stays fully stylable, the SVG loaded through <image> is treated as a flattened, opaque picture, exactly like a PNG would be.Real-world use case
In an interface, <image> typically displays a partner or payment logo next to vector-drawn elements, embeds a screenshot inside an explanatory diagram, or loads a complex external SVG icon without having to copy its entire markup into the document.
FAQ
<image> be animated like the rest of the document?The rectangle that hosts it can be moved, resized or animated normally, but the internal content of the loaded SVG file stays frozen: its own shapes are not reachable from the document that embeds it.
width and height always need to be set?Yes, in the vast majority of browsers an image without an explicit width or height simply does not render at all, unlike an HTML tag where the image keeps its natural dimensions by default.
Yes, the href attribute accepts a data URI string directly, which avoids a separate network request and keeps the SVG entirely self-contained in a single file, handy for an export or an email.