SVG Embedded Content – Using <image> & <foreignObject>

SVG embedded content refers to external resources such as raster images or HTML fragments that are incorporated into an SVG document. Aspose.SVG supports embedding these resources using the <image> and <foreignObject> elements.

Loading and Displaying Bitmaps – <image> Element

The SVG <image> element allows to include and render bitmaps within an SVG object. It can display image formats JPEG, PNG and the SVG pictures too. Attributes of the <image> element indicate that the contents of a file (a bitmap) should be displayed into a given rectangle (viewport) within the current user coordinate system.

Attributes

• x and y – Coordinates of the top‑left corner of the image viewport.
• width and height – Size of the viewport (required).
• href / xlink:href – URL of the external image file.
• preserveAspectRatio – Controls scaling behavior of the image.

How to use the SVG <image> element? The following code snippet shows as a .png and .svg images can embed inside the SVG document:

<svg width="500" height="400" xmlns="http://www.w3.org/2000/svg">
    <image href="https://docs.aspose.com/svg/images/svg.png" x="20" y="20" height="180" width="180" />
    <image href="https://docs.aspose.com/svg/files/shapes.svg" x="250" y="10" height="350" width="350" />
    <text x="40" y="250">Embedded PNG image</text>
    <text x="300" y="250">Embedded SVG image</text>
</svg>

The above code snippet is displayed like this:

HTML inside SVG – <foreignObject> Element

SVG is designed to be consistent with other XML languages for describing and rendering of embedded content. The <foreignObject> element allows to include in SVG file the elements in a non-SVG namespace. In the context of a browser, it is most likely HTML. The foreign graphical content can be processed with transformations, filters, clipping, masking and compositing.

Attributes

• x, y – Position of the foreign object’s top‑left corner.
• width, height – Dimensions of the container (required for rendering).

Let’s see an example:

<svg viewBox="0 0 300 300" xmlns="http://www.w3.org/2000/svg">
    <style>
        div {
            color: grey;
            font: 14px serif;
            }
    </style>
    <circle cx="65" cy="60" r="60" fill="red" fill-opacity="0.1" />
    <!-- example of  HTML text embedding in SVG -->
    <foreignObject x="20" y="20" width="200" height="180">
    <!--In the context of HTML embedded in the SVG document, the XHTML namespace is mandatory-->
        <div xmlns="https://www.w3.org/1999/xhtml">
        Convert SVG to PNG. Aspose.SVG for .NET can read and convert SVG files to PNG, PDF, XPS, and major image formats. 
        </div>
    </foreignObject>
</svg>

Using <foreignObject> requires declaring the correct XML namespace for the foreign markup, as shown on line 12 of the example.

Common Mistakes and Fixes

Problem	Cause	Solution
Image does not appear	Missing width/height attributes on <image>	Add explicit width and height values to define the viewport
HTML inside <foreignObject> is invisible	Incorrect or missing XHTML namespace	Include xmlns="https://www.w3.org/1999/xhtml" on the root HTML element
Image is stretched	preserveAspectRatio not set or set to none	Use preserveAspectRatio="xMidYMid meet" (or another appropriate value) to maintain aspect ratio
SVG fails to load in older browsers	Use of href without fallback xlink:href	Provide both href and xlink:href attributes for better compatibility

Quick Recipes

• Embed a PNG image

  <svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
      <image href="https://docs.aspose.com/svg/images/drawing/aspose.png" x="0" y="0" width="200" height="200"/>
  </svg>

• Embed an external SVG file

  <svg width="300" height="300" xmlns="http://www.w3.org/2000/svg">
      <image href="https://docs.aspose.com/svg/images/face.svg" x="10" y="10" width="280" height="280"/>
  </svg>

• Preserve image aspect ratio

  <svg width="250" height="250" xmlns="http://www.w3.org/2000/svg">
      <image href="https://example.com/photo.jpg"
             x="0" y="0"
             width="250" height="250"
             preserveAspectRatio="xMidYMid meet"/>
  </svg>

Conclusion

Embedding raster images and HTML fragments inside SVG expands the creative possibilities of vector graphics. By mastering the <image> and <foreignObject> elements, you can build rich, interactive visualizations that combine the scalability of SVG with the flexibility of external media.

Next Steps

• Learn how to draw shapes and paths in SVG: SVG Shapes
• Explore text handling and font embedding: SVG Text
• Discover advanced transformations in SVG: SVG Transformations