"<feImage>"

<feImage> imports an external image — or a fragment of the current document — into the filter graph as an additional input.

It's how you use a photograph as a lighting source, mask, or displacement map, or how you reuse an existing SVG element's rendering as an input to another primitive like "<feDisplacementMap>" or "<feComposite>".

Conceptually, <feImage> is a tiny "load this picture into the filter canvas" primitive. It doesn't take a filter input (no in attribute); instead, its source is pointed at by the href attribute. The result fills the primitive subregion at the <feImage>'s x, y, width, height, and downstream primitives can use it just like any other input.

• DOM object: SVGFEImageElement
• SVG2 spec: https://www.w3.org/TR/filter-effects/#feImageElement

How href works

The href attribute accepts either:

• An external URL pointing at an image file (PNG, JPEG, SVG, etc.), e.g. href="texture.png" or href="https://example.com/photo.jpg". The file is loaded and its pixels are rasterized into the filter subregion.
• A fragment reference of the form #id pointing at another element in the same document, e.g. href="#myShape". The referenced element is rendered to its own bounding box, and the resulting pixels are handed to the filter as if they were an image.

How preserveAspectRatio works

When the source image's aspect ratio doesn't match the destination rectangle (the filter primitive subregion), preserveAspectRatio decides whether to stretch, letterbox, or crop the image so that it fits.

The attribute is a pair: <align> <meetOrSlice>.

• <align> picks which corner or edge of the source is aligned to which corner or edge of the destination when there's extra space. Valid values: none, xMinYMin, xMidYMin, xMaxYMin, xMinYMid, xMidYMid (the default), xMaxYMid, xMinYMax, xMidYMax, xMaxYMax. The x* part controls horizontal alignment (Min = left, Mid = center, Max = right); the Y* part controls vertical alignment (Min = top, Mid = middle, Max = bottom).
• <meetOrSlice> picks the fitting mode:
  • meet (the default) — scale the image uniformly so it fits entirely inside the destination. If aspect ratios differ, you get letterboxing (empty bars on one axis). Think "fit".
  • slice — scale the image uniformly so it entirely covers the destination. If aspect ratios differ, the image is cropped on one axis. Think "fill".
• none as the alignment value disables aspect-ratio preservation entirely: the image is stretched non-uniformly to exactly fill the destination rectangle. <meetOrSlice> is ignored when alignment is none.

The default is xMidYMid meet.

The diagram below shows the same square source image fitted into a wider landscape destination rectangle under meet, slice, and none. The dashed box is the destination; the shaded area shows where the image pixels actually land:

Example 1: external image as a filter input

The simplest use of <feImage>: load an external PNG and output it as the filter result. The filter completely replaces the source graphic with the loaded image. In practice you'd usually combine it with a compositing primitive to mix it with the source:

<filter id="LoadImage">
  <feImage href="texture.png" />
</filter>
<rect width="90" height="70" filter="url(#LoadImage)" />

Example 2: referencing an inline element by id

href="#star" points at another element in the same document. The filter re-renders that element into its own bounding box and uses those pixels as the filter output. This is a handy way to reuse a shape (or a group of shapes) as input to a downstream primitive without duplicating geometry:

<defs>
  <polygon id="star" points="45,5 55,35 85,35 60,55 70,85 45,65 20,85 30,55 5,35 35,35"
           fill="gold" stroke="orange" />
  <filter id="UseStar">
    <feImage href="#star" />
  </filter>
</defs>
<rect width="90" height="80" filter="url(#UseStar)" />

Example 3: feeding feDisplacementMap

Here <feImage> produces a gradient, which is then fed to <feDisplacementMap> as the displacement source. The gradient's red and green channels push the source graphic's pixels around, producing a warp. This is a common pattern for effects that need a custom "map" input (lighting normals, displacement fields, texture lookups):

<filter id="Warp">
  <feImage href="#gradient" result="map" />
  <feDisplacementMap in="SourceGraphic" in2="map" scale="20" />
</filter>

Attributes

Attribute	Default	Description
href	(none)	URL or in-document fragment reference (#id) for the source image.
preserveAspectRatio	xMidYMid meet	How the source is fitted into the primitive subregion when aspect ratios differ. See above.
crossorigin	(none)	CORS setting for external URL loads (anonymous or use-credentials).

Inherits standard filter primitive attributes (in, result, x, y, width, height) from donner::svg::SVGFilterPrimitiveStandardAttributes.