3.6 The <use> element

Any <svg>, <symbol>, <g>, or graphics element that is a child of a <defs> element and has been assigned an ID is potentially a template object that can be re-used (i.e., "instanced") anywhere in the SVG document via a <use> element. The <use> element references another element and indicates that the graphical contents of that element should be included/drawn at that given point in the document.

The <use> element can reference either:

Unlike <image>, the <use> element cannot reference entire files.

In the example below, the first <g> element has inline content. After this comes a <use> element whose href value indicates which graphics element should be included/rendered at that point in the document. Finally, the second <g> element has both inline and referenced content. In this case, the referenced content will draw first, followed by the inline content. 

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <defs>
    <symbol id="TemplateObject01">
      <!-- symbol definition here -->
    </symbol>
  </defs>

  <desc>Examples of inline and referenced content
  </desc>
  
  <!-- <g> with inline content -->
  <g>
    <!-- Inline content goes here -->
  </g>

  <!-- referenced content -->
  <use xlink:href="#TemplateObject01" />

  <!-- <g> with both referenced and inline content -->
  <g>
    <use xlink:href="#TemplateObject01" />
    <!-- Inline content goes here -->
  </g>
</svg>

Download this example

The <use> element has optional attributes x, y, width and height which are used to map the graphical contents of the referenced element onto a rectangular region within the current coordinate system.

The effect of a <use> element is as if the contents of the referenced element were deeply cloned into a separate non-exposed DOM tree which had the <use> element as its parent and all of the <use> element's ancestors as its higher-level ancestors. Because the cloned DOM tree is non-exposed, the SVG Document Object Model (DOM) only contains the <use> element and its attributes. The SVG DOM does not show the referenced element's contents as children of <use> element.

Property inheritance, however, works as if the referenced element had been textually included as a deeply cloned child of the <use> element. The referenced element inherits properties from the <use> element and the <use> element's ancestors. An instance of a referenced element does not inherit properties from its original parents.

The following example illustrates property inheritance with the <use> element: 

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <defs style="stroke:green">
    <!-- Note that parent's stroke:green will be ignored below -->
    <circle id="TemplateObject02" cx="50" cy="50" r="30" style="fill:red" />
  </defs>

  <desc>Examples of <use> property inheritance
  </desc>
  
  <g style="fill:yellow;stroke:blue" >
    <!-- Draws a circle with fill:red and stroke:blue. -->
    <!-- Note that the referenced element specifies fill:red,
         which takes precedence over the inherited fill:yellow. -->
    <use xlink:href="#TemplateObject02" />
  </g>
</svg>

Download this example

In the example above, property inheritance for <use> element shown above is as if the <use> element were replaced a container object which contents are the referenced element: 

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <defs style="stroke:green">
    <!-- Note that parent's stroke:green will be ignored below -->
    <circle id="TemplateObject02" cx="50" cy="50" r="30" style="fill:red" />
  </defs>

  <desc>Examples of <use> property inheritance
  </desc>
  
  <g style="fill:yellow;stroke:blue" >
    <!-- Draws a circle with fill:red and stroke:blue. -->
    <!-- Note that the referenced element specifies fill:red,
         which takes precedence over the inherited fill:yellow. -->
    <g>
      <circle cx="50" cy="50" r="30" style="fill:red" />
    </g>
  </g>
</svg>

  
<!ELEMENT use (desc?,title?) >
<!ATTLIST use
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  transform CDATA #IMPLIED
  %graphicsElementEvents;
  system-required CDATA #IMPLIED
  x CDATA #IMPLIED
  y CDATA #IMPLIED
  width CDATA #IMPLIED
  height CDATA #IMPLIED
  xmlns:xlink CDATA #FIXED "http://www.w3.org/XML/XLink/0.9"
  xlink:type (simple|extended|locator|arc) #FIXED "simple" 
  xlink:role CDATA #IMPLIED
  xlink:title CDATA #IMPLIED
  xlink:show (new|parsed|replace) #FIXED 'parsed'
  xlink:actuate (user|auto) #FIXED 'auto'
  xlink:href CDATA #REQUIRED >

Attribute definitions:

x = "x-coordinate"
The x-coordinate of one corner of the rectangular region into which the referenced element should be placed. The default x-coordinate is zero. See Coordinate Systems, Transformations and Units. (??? Needs to be expanded to take care of referencing graphics elements.)
y = "y-coordinate"
The y-coordinate of one corner of the rectangular region into which the referenced element should be placed. The default y-coordinate is zero. See Coordinate Systems, Transformations and Units. (??? Needs to be expanded to take care of referencing graphics elements.)
width = "length"
The width of the rectangular region into which the referenced element should be placed. (??? Default value?) (??? Needs to be expanded to take care of referencing graphics elements.)
height = "length"
The height of the rectangular region into which the referenced element should be placed. (??? Default value?) (??? Needs to be expanded to take care of referencing graphics elements.)
href = "uri-reference"
A URI reference to an element/fragment within an SVG document.

Attributes defined elsewhere:
id, xml:lang, xml:space, class, style, transform, %graphicsElementEvents;, system-required, xmlns:xlink, xlink:type, xlink:role, xlink:title, xlink:show, xlink:actuate.