4 SVG Document Structure


4.1 Introduction

Each SVG document is contained within an <svg> outermost element.

An SVG "document" can range from a single SVG graphics element such as a rectangle to a complex, deeply nested collection of grouping and graphics elements. Also, an SVG document can be embedded inline as a fragment within a parent document (an expectedly common situation with an XML Web pages) or it can stand by itself as a self-contained graphics file.

The following example shows a simple SVG document embedded as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the <svg> and <rect> elements belong to the SVG namespace:

<?xml version="1.0" standalone="yes"?>
<parent xmlns="http://someplace.org"
       xmlns:svg="http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
   <!-- parent stuff here -->
   <svg:svg width="5cm" height="8cm">
      <svg:ellipse rx="200" ry="130" />
   </svg:svg>
   <!-- ... -->
</parent>

Download this example

This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <desc>Four separate rectangles
  </desc>
    <rect width="20" height="60"/>
    <rect width="30" height="70"/>
    <rect width="40" height="80"/>
    <rect width="50" height="90"/>
</svg>

Download this example

<svg> elements can appear in the middle of SVG documents. This is the mechanism by which SVG documents can be embedded within other SVG documents.

Another use for <svg> elements within the middle of SVG documents is to establish a new viewport and alter the meaning of CSS unit specifiers. See Establishing a New Viewport: the <svg> element within an SVG document and Redefining the meaning of CSS unit specifiers. .

4.2 Grouping and Naming Collections of Drawing Elements: the <g> Element

The <g> element is the element for grouping and naming collections of drawing elements. If several drawing elements share similar attributes, they can be collected together using a <g> element. For example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <desc>Two groups, each of two rectangles
  </desc>
  <g style="fillcolor:red">
    <rect x="100" y="100" width="100" height="100" />
    <rect x="300" y="100" width="100" height="100" />
  </g>
  <g style="fillcolor:blue">
    <rect x="100" y="300" width="100" height="100" />
    <rect x="300" y="300" width="100" height="100" />
  </g>
</svg>

Download this example

A group of drawing elements, as well as individual objects, can be given a name. Named groups are needed for several purposes such as animation and re-usable objects. The following example organizes the drawing elements into two groups and assigns a name to each group:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <desc>Two named groups
  </desc>
  <g id="OBJECT1">
    <rect x="100" y="100" width="100" height="100" />
  </g>
  <g id="OBJECT2">
    <circle cx="150" cy="300" r="25" />
  </g>
</svg>

Download this example

A <g> element can contain other <g> elements nested within it, to an arbitrary depth. Thus, the following is valid SVG:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <desc>Groups can nest
  </desc>
  <g>
     <g>
       <g>
       </g>
     </g>
   </g>
</svg>

Download this example

Any drawing element that is not contained within a <g> is treated (at least conceptually) as if it were in its own group.

4.3 Defining referenced and undrawn elements: the <defs> element

Every graphics element (???) in SVG can have a child <defs> element. The two main purpose of the <defs> element are:

A <defs> element defines the child elements that are contained within it. The child elements are not drawn at definition.

The following example shows how a undrawn rectangle and a gradient can be defined within a <defs> element so that they can be referenced later in the document:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <defs>
    <rect id="TemplateObject01" width="100" height="37.34"/>
    <lineargradient id="Gradient01">
      <stop offset="30%" style="color:#39F"/>
    </lineargradient>
  </defs>
  <desc>Defining things for later use
  </desc>
  <!-- SVG elements in here would reference/use 
       the elements defined in the <defs> -->
</svg>

Download this example

4.3.1 The <style> sub-element to <defs>

A <style> element can appear as a subelement to any <defs> element. A <style> element is equivalent to the <style> element in HTML and thus can contain any valid CSS definitions. Any CSS definitions within any <style> element have a "global" scope across the entire current SVG document. It is useful to structurally associate style with each definition, so that the style is available when the definition is used (possibly from another SVG graphic).

The following is an example of defining and using a text style:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <defs>
    <style><![CDATA[
      .TitleText { font-size: 16; font-family: Helvetica } ]]>
    </style>
  </defs>
  <text class="TitleText">Here is my title</text>
</svg>

Download this example

4.3.2 The <script> sub-element to <defs>

A <script> element can appear as a subelement to any <defs> element. A <script> element is equivalent to the <script> element in HTML and thus is the place for scripts (e.g., ECMAScript). Any functions defined within any <script> element have a "global" scope across the entire current SVG document.

The following is an example of defining an ECMAScript function and defining an event handler that invokes that function:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <defs>
    <script><![CDATA[
      /* Beep on mouseclick */
      MouseClickHandler() { beep(); }
     ]]>
    </script>
  </defs>
  <circle onclick="MouseClickHandler()" r="85"/>
</svg>

Download this example

4.4 The <symbol> element

The <symbol> element is used to define graphical objects which are meant for any of the following uses:

Closely related to the <symbol> element are the <marker> and <pattern> elements.

A <symbol> element can contain the same graphic elements that are allowed in <svg> and <g> elements. A <symbol> element has the following additional attributes to meet the needs of the above situations:

4.5 The <use> element

Any <svg>, <symbol>, <g> or graphics element defined within a <defs> and assigned an ID is potentially a template object that can be re-used (i.e., "instanced") anywhere in the SVG document.

The <use> element references another graphics object and indicates that the contents of that graphics object should be included/drawn at that given point in the document. The <use> element conforms to XLink [??? Include reference to XLink]. (Note that the XLink specification is currently under development and is subject to change. The SVG working group will track and rationalize with XLink as it evolves.)

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 predefined graphics object 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 July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.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 href="#TemplateObject01" />

  <!-- <g> with both referenced and inline content -->
  <g>
    <use 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 a referenced <symbol> element onto a rectangular region within the current coordinate system. The 'transform' property can also be applied to do a subsequent transformation of the symbol's coordinates after those coordinates are mapped onto the rectangular region.

Any graphics attributes specified on a <use> element override the attributes specified on the template/referenced element. For example, if the stroke-width on the template object is 10 but the <use> specifies a stroke-width of 20, then the object will draw with a stroke-width of 20.

The <use> element does not do the equivalent of a macro expansion. The SVG Document Object Model (DOM) only contains a <use> element and its attributes.

4.6 The <image> element

The <image> element indicates that the contents of a complete file should be rendered into a given rectangle within the current user coordinate system. The <image> element can refer to image files such as PNG or JPEG or to files with MIME type of "image/svg". Conforming SVG viewers need to support at least PNG, JPEG and SVG format files.

For more on image objects, refer to Images.

Unlike <use>, the <image> element cannot reference elements within an SVG file.