An SVG document is contained within an <svg> element, which is required to be the outermost element in an SVG document.
An SVG "document" can range from a single SVG graphics element such as a <rect> to a complex, deeply nested collection of container elements and graphics elements. Also, an SVG document can be embedded inline as a fragment within a parent document (an expectedly common situation within 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 <ellipse> 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-19990812.dtd"> <!-- parent stuff here --> <svg:svg width="5cm" height="8cm"> <svg:ellipse rx="200" ry="130" /> </svg:svg> <!-- ... --> </parent>
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 August 1999//EN" "http://www.w3.org/Graphics/SVG/SVG-19990812.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>
<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.
<!ELEMENT svg (defs?,desc?,title?, (path|text|rect|circle|ellipse|line|polyline|polygon| use|image|svg|g|switch|a)*)> <!ATTLIST svg xmlns CDATA #FIXED 'http://www.w3.org/Graphics/SVG/SVG-19990812.dtd' id ID #IMPLIED xml:lang NMTOKEN #IMPLIED xml:space (default|preserve) #IMPLIED class NMTOKENS #IMPLIED style CDATA #IMPLIED %graphicsElementEvents; %documentEvents; system-required CDATA #IMPLIED x CDATA #IMPLIED y CDATA #IMPLIED width CDATA #REQUIRED height CDATA #REQUIRED refX CDATA #IMPLIED refY CDATA #IMPLIED viewBox CDATA #IMPLIED preserveAspectRatio CDATA 'xMidYMid meet' allowZoomAndPan (true | false) "true" contentScriptType CDATA #IMPLIED > |
Attribute definitions:
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 August 1999//EN" "http://www.w3.org/Graphics/SVG/SVG-19990812.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>
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 August 1999//EN" "http://www.w3.org/Graphics/SVG/SVG-19990812.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>
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 August 1999//EN" "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd"> <svg width="4in" height="3in"> <desc>Groups can nest </desc> <g> <g> <g> </g> </g> </g> </svg>
Any drawing element that is not contained within a <g> is treated (at least conceptually) as if it were in its own group.
<!ELEMENT g (defs?,desc?,title?, (path|text|rect|circle|ellipse|line|polyline|polygon| use|image|svg|g|switch|a| animate|animateTransform|animateColor)*)> <!ATTLIST g 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> |
SVG makes extensive use of URI references [URI] to other objects. For example, to fill a rectangle with a linear gradient, you first define a <linearGradient> element and give it an ID, as in:
<linearGradient id="MyGradient">...</linearGradient>
You then reference the linear gradient as the value of the 'fill' property for the rectangle, as in:
<rect style="fill:url(#MyGradient)"/>
In SVG, among the facilities that allow URI references are:
URI references are defined in either of the following forms:
<URI-reference> = [ <absoluteURI> | <relativeURI> ] [ "#" <elementID> ] -or- <URI-reference> = [ <absoluteURI> | <relativeURI> ] [ "#xptr(id(" <elementID> "))" ]
where <elementID> is the ID of the referenced element.
(Note that the two forms above (i.e., #<elementID> and #xptr(id(<elementID>))) are formulated in syntaxes compatible with "XML Pointer Language (XPointer)" [XPTR]. These two formulations of URI references are the only XPointer formulations that are required in SVG 1.0 user agents.)
SVG supports two types of URI references:
The following rules apply to the processing of URI references:
Invalid references should be treated as if no value were provided for the referencing attribute or property. For example, if there is no element with ID "BogusReference" in the current document, then fill="url(#BogusReference)" would represent an invalid reference. In cases like this, the element should be processed as if no 'fill' property were provided. In those cases where a list of property values are possible and one of the property values is an undefined reference, then the list will be processed as if the invalid reference were removed from the list.
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 |
The <defs> element is used to identify those objects which will be referenced by other objects later in the document. It is a requirement that all referenced objects be defined within a <defs> element. (See References and the <defs> element.)
The child elements within a <defs> element are not drawn.
<!ELEMENT defs (script|style|symbol|marker|clipPath|mask| linearGradient|radialGradient|pattern|filter|cursor|font| animate|animateMotion|animateTransform|animateColor|animateFlipbook| path|text|rect|circle|ellipse|line|polyline|polygon| use|image|svg|g|switch)* > <!ATTLIST defs id ID #IMPLIED xml:lang NMTOKEN #IMPLIED xml:space (default|preserve) #IMPLIED class NMTOKENS #IMPLIED style CDATA #IMPLIED> |
To provide some SVG user agents with an opportunity to implement efficient implementations in streaming environments, creators of SVG documents are encouraged to place all elements which are targets of local URI references within a <defs> element which is a direct child of one of the ancestors of the referencing element. For example:
<?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"> <desc>Local URI references within ancestor's <defs> element.</desc> <defs> <linearGradient id="Gradient01"> <stop offset="30%" style="color:#39F"/> </linearGradient> </defs> <g> <g> <rect x="0%" y="0%" width="100%" height="100%" style="fill:url(#Gradient01)" /> </g> </g> </svg>
In the document above, the linear gradient is defined within a <defs> element which is the direct child of the <svg> element, which in turn is an ancestor of the <rect> element which references the linear gradient. Thus, the above document conforms to the guideline.
Each container element or graphics element in an SVG drawing can supply a <desc> and/or a <title> description string where the description is text-only. These description strings provide information about the graphics to visually impaired users. User agents which can process SVG in most cases will ignore the description strings (except that the <title> might be used to provide a tooltip).
The following is an example. In typical operation, the SVG user agent would ignore (i.e., not display) the <desc> element and the <title> elements and would render the remaining contents of the <g> element.
If this file were processed by an older browser (i.e., a browser that doesn't have SVG support), then the browser would treat the file as HTML. All SVG elements would not be recognized and therefore ignored. The browser would render all character data (including any character data within <desc> and <title> elements) within the current text region using current text styling parameters.
<?xml version="1.0" standalone="no"?> <!DOCTYPE svg SYSTEM "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd"> <svg width="4in" height="3in"> <g> <title> Company sales by region </title> <desc> This is a bar chart which shows company sales by region. </desc> <!-- Bar chart defined as vector data --> </g> </svg>
Description and title elements can contain marked-up text from other namespaces. Here is an example:
<?xml version="1.0" standalone="yes"?> <svg width="4in" height="3in" xmlns="http://www.w3.org/Graphics/SVG/SVG-19990812.dtd"> <desc xmlns:mydoc="http://foo.org/mydoc"> <mydoc:title>This is an example SVG file</mydoc:title> <mydoc:para>The global description uses markup from the <mydoc:emph>mydoc</mydoc:emph> namespace.</mydoc:para> </desc> <g> <!-- the picture goes here --> </g> </svg>
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.
<!ELEMENT symbol (defs?,desc?,title?, (path|text|rect|circle|ellipse|line|polyline|polygon| use|image|svg|g|switch|a| animate|animateTransform|animateColor)*)> <!ATTLIST symbol id ID #IMPLIED xml:lang NMTOKEN #IMPLIED xml:space (default|preserve) #IMPLIED class NMTOKENS #IMPLIED style CDATA #IMPLIED refX CDATA #IMPLIED refY CDATA #IMPLIED viewBox CDATA #IMPLIED preserveAspectRatio CDATA 'xMidYMid meet' > |
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>
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>
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?,(animate|animateTransform|animateColor)*) > <!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:
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 raster 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.
Unlike <use>,
the <image> element cannot reference elements within
an SVG file.
<!ELEMENT image (desc?,title?,(animate|animateTransform)*) > <!ATTLIST image 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 #REQUIRED height CDATA #REQUIRED 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:
A valid example:
<?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"> <desc>This graphic links to an external image </desc> <image x="200" y="200" width"100px" height="100px" xlink:href="myimage.png"> <title>My image</title> </image> </svg>
A well-formed example:
<?xml version="1.0" standalone="yes"?> <svg width="4in" height="3in" xmlns='http://www.w3.org/Graphics/SVG/SVG-19990812.dtd'> <desc>This links to an external image </desc> <image x="200" y="200" width"100px" height="100px" xlink:type="simple" xlink:show="replace" xlink:actuate="user" xlink:href="myimage.png"> <title>My image</title> </image> </svg>