<use>

<use> instantiates another element at a specified position, cloning its rendered output.

It's the SVG equivalent of "put another copy of that shape over here" - commonly used for reusable icon libraries, tilesets, symbol sheets, and anywhere you'd otherwise copy-paste the same shape multiple times. Define your artwork once (typically inside <defs> or a <symbol>), then stamp it out wherever you need it with <use href="#id" x="..." y="..." />.

The cloned content inherits styles from the <use> element itself, so a single symbol can be re-coloured per instance by setting fill, stroke, etc. on each <use>. The clones remain linked to the referenced source and automatically reflect later DOM mutations to the original.

• DOM object: SVGUseElement
• SVG spec: https://www.w3.org/TR/SVG2/struct.html#UseElement

Example 1: basic reuse

Define a circle once, then stamp a second instance at x="100" with a different fill:

<svg width="200" height="100">
  <circle id="a" cx="50" cy="50" r="40" stroke="blue" />
  <use href="#a" x="100" fill="blue" />
</svg>

Example 2: icon library via symbol

A <symbol> is a template that isn't rendered on its own - it's only visible through a <use> reference. Symbols can declare their own viewBox, which makes them resolution independent: the <use> element's width and height decide how big the instance is, and the symbol's viewBox is mapped into that box:

<defs>
  <symbol id="star" viewBox="0 0 100 100">
    <polygon points="50,5 61,39 97,39 68,60 79,95 50,74 21,95 32,60 3,39 39,39"
             fill="gold" stroke="orange" stroke-width="3" />
  </symbol>
</defs>
<use href="#star" x="10"  y="20" width="60" height="60" />
<use href="#star" x="90"  y="20" width="60" height="60" />
<use href="#star" x="170" y="20" width="60" height="60" />

How referenced viewports are fitted

When <use> references a <symbol> or nested <svg> element that has its own viewBox, the referenced element's preserveAspectRatio attribute decides how that content is fitted into the <use> element's width/height box. It answers the question: "when the symbol's intrinsic aspect ratio doesn't match the destination rectangle, should we stretch, letterbox, or crop?"

Donner parses preserveAspectRatio on the referenced <symbol> or <svg>, not on the <use> element itself. Put the fitting mode on the element being reused.

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

• <align> picks which corner or edge of the source content 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 content uniformly so it fits entirely inside the destination. If aspect ratios differ, there's empty space on one axis. Think "fit".
  • slice - scale the content uniformly so it entirely covers the destination. If aspect ratios differ, the content is cropped on one axis. Think "fill".
• none as the alignment value disables aspect-ratio preservation entirely: the content is stretched non-uniformly to exactly fill the destination rectangle. <meetOrSlice> is ignored when alignment is none.

The default is xMidYMid meet.

Example 3: referenced preserveAspectRatio comparison

All three instances reference square symbols (viewBox="0 0 100 100") and are sized into a wider 120×60 rectangle (dashed outline). Only the referenced symbol's preserveAspectRatio differs:

<symbol id="fit" viewBox="0 0 100 100" preserveAspectRatio="xMidYMid meet"> ... </symbol>
<symbol id="fill" viewBox="0 0 100 100" preserveAspectRatio="xMidYMid slice"> ... </symbol>
<symbol id="stretch" viewBox="0 0 100 100" preserveAspectRatio="none"> ... </symbol>
 
<use href="#fit" width="120" height="60" />
<use href="#fill" width="120" height="60" />
<use href="#stretch" width="120" height="60" />

Note: the referenced element's preserveAspectRatio only has an effect when that element has an intrinsic coordinate system (a viewBox). Referencing a bare <circle> or <path> does not create a fitted viewport.

Attributes

Attribute	Default	Description
href	(none)	URI (typically #id) of the element to reuse.
x	0	X coordinate where the referenced element is placed.
y	0	Y coordinate where the referenced element is placed.
width	auto	Width of the instance. Only meaningful when the referenced element has a viewBox (e.g. <symbol> or <svg>).
height	auto	Height of the instance. Only meaningful when the referenced element has a viewBox.