SVG 2 – 04 May 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 4: Document Structure

4.1. Defining an SVG document fragment: the ‘svg’ element

4.1.1. Overview

The content model and set of allowed attributes, as listed in definitions.xml, needs to be reviewed for consistency across all elements.

An SVG document fragment consists of any number of SVG elements contained within an svg element.

An SVG document fragment can range from an empty fragment (i.e., no content inside of the svg element), to a very simple SVG document fragment containing a single SVG graphics element such as a rect, to a complex, deeply nested collection of container elements and graphics elements.

An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent HTML or XML document.

The following example shows simple SVG content embedded inline 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://example.org"
        xmlns:svg="http://www.w3.org/2000/svg">
   <!-- parent contents here -->
   <svg:svg width="4cm" height="8cm">
      <svg:ellipse cx="2cm" cy="4cm" rx="2cm" ry="1cm" />
   </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"?>
<svg width="5cm" height="4cm" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Four separate rectangles
  </desc>
    <rect x="0.5cm" y="0.5cm" width="2cm" height="1cm"/>
    <rect x="0.5cm" y="2cm" width="1cm" height="1.5cm"/>
    <rect x="3cm" y="0.5cm" width="1.5cm" height="2cm"/>
    <rect x="3.5cm" y="3cm" width="1cm" height="0.5cm"/>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="3.98cm"
        fill="none" stroke="blue" stroke-width=".02cm" />

</svg>

svg elements can appear in the middle of SVG content. This is the mechanism by which SVG document fragments can be embedded within other SVG document fragments.

Another use for svg elements within the middle of SVG content is to establish a new SVG viewport. (See Establishing a new SVG viewport.)

4.1.2. Namespace

When SVG is parsed as a XML, for compliance with the Namespaces in XML Recommendation [XML-NS], an SVG namespace declaration must be provided so that all SVG elements are identified as belonging to the SVG namespace.

When using the HTML syntax, the namespace is provided automatically by the HTML parser.

<html>
<svg viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="50" fill="green">
</svg>
</html>

As the example shows there's no need to have an ‘xmlns’ attribute declaring that the element is in the SVG namespace when using the HTML parser. The HTML parser will automatically create the SVG elements in the proper namespace.

This section should talk about how a document's behavior is defined in terms of the DOM, and also explain how the HTML parser can create SVG fragments.

The SVG 2 namespace is http://www.w3.org/2000/svg, which is the same as for earlier versions of SVG.

The following are possible ways to provide a namespace declaration when SVG is parsed as XML. An ‘xmlns’ attribute without a namespace prefix could be specified on an svg element, which means that SVG is the default namespace for all elements within the scope of the element with the ‘xmlns’ attribute:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <rect x="10" y="10" width="80" height="80" fill="green" />
</svg>

If a namespace prefix is specified on the ‘xmlns’ attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"), then the corresponding namespace is not the default namespace, so an explicit namespace prefix must be assigned to the elements:

<svg:svg xmlns:svg="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <svg:rect x="10" y="10" width="80" height="80" fill="green" />
</svg:svg>

Namespace prefixes can be specified on ancestor elements (illustrated in the above example). For more information, refer to the Namespaces in XML Recommendation [XML-NS].

4.1.3. Definitions

structural element
The structural elements are those which define the primary structure of an SVG document. Specifically, the following elements are structural elements: defs, g, svg, symbol and use.
structurally external element
Elements that define its structure by reference to an external resource. Specifically, the following elements are structurally external elements when they have an ‘href’ attribute: audio, foreignObject, iframe, image, script, use and video.
SVG user agent
An SVG user agent is a user agent that is able to retrieve and render SVG content.
user agent

The general definition of a user agent is an application that retrieves and renders Web content, including text, graphics, sounds, video, images, and other content types. A user agent may require additional user agents that handle some types of content. For instance, a browser may run a separate program or plug-in to render sound or video. User agents include graphical desktop browsers, multimedia players, text browsers, voice browsers, and assistive technologies such as screen readers, screen magnifiers, speech synthesizers, onscreen keyboards, and voice input software.

A "user agent" may or may not have the ability to retrieve and render SVG content; however, an "SVG user agent" retrieves and renders SVG content.

current SVG document fragment
The document sub-tree which starts with the outermost ancestor svg element of a given SVG element, with the requirement that all container elements between the outermost svg and the given element are all elements in the SVG namespace.
outermost svg element
The furthest svg ancestor element that remains in the current SVG document fragment.
SVG document fragment
A document sub-tree which starts with an svg element which is either the root element of the document or whose parent element is not in the SVG namespace. An SVG document fragment can consist of a stand-alone SVG document, or a fragment of a parent document enclosed by an svg element. When an svg element is a descendant of another svg element, only the outermost svg element is the root of an SVG document fragment.
SVG elements
Any element in the SVG namespace.
graphics element
One of the element types that can cause graphics to be drawn onto the target canvas. Specifically: audio, canvas, circle, ellipse, foreignObject, iframe, image, line, path, polygon, polyline, rect, text, use and video.
graphics referencing element
A graphics element which uses a reference to a different document or element as the source of its graphical content. Specifically: audio, iframe, image, use and video.

4.1.4. The ‘svg’ element

SVG 2 Requirement: Support transforming svg elements.
Resolution: We will allow ‘transform’ on ‘svg’ in SVG 2.
Purpose: To allow transforms on nested svg elements, in line with author expectations.
Owner: Dirk (no action)
Status: Done
svg
Categories:
Container element, renderable element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
Geometry properties:
DOM Interfaces:

The x and y attributes specify the top-left corner of the rectangular region into which an embedded svg element is placed. On an outermost svg element, these attributes have no effect.

For outermost svg elements, the width and height attributes specify the intrinsic size of the SVG document fragment. For embedded svg elements, they specify the size of the rectangular region into which the svg element is placed.

Attribute definitions:

Name Value Initial value Animatable
zoomAndPan disable | magnify magnify no

Specifies whether the user agent should supply a means to zoom and pan the SVG content. See the definition of zoomAndPan for details.

If an SVG document is likely to be referenced as a component of another document, the author will often want to include a viewBox attribute on the outermost svg element of the referenced document. This attribute provides a convenient way to design SVG documents to scale-to-fit into an arbitrary SVG viewport.

The svg element exposes as event handler content attributes a number of the event handlers of the Window object. It also mirrors their event handler IDL attributes.

The onblur, onerror, onfocus, onload, and onscroll event handlers of the Window object, exposed on the svg element, replace the generic event handlers with the same names normally supported by SVG elements.

4.2. Grouping: the ‘g’ element

4.2.1. Overview

container element
An element which can have graphics elements and other container elements as child elements. Specifically: a, clipPath, defs, g, marker, mask, pattern, svg, switch and symbol.

The g element is a container element for grouping together related graphics elements.

A group of elements, as well as individual objects, can be given a name using the id attribute. Named groups are needed for several purposes such as animation and re-usable objects.

An example:

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="5cm" height="5cm">
  <desc>Two groups, each of two rectangles</desc>
  <g id="group1" fill="red">
    <rect x="1cm" y="1cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="1cm" width="1cm" height="1cm"/>
  </g>
  <g id="group2" fill="blue">
    <rect x="1cm" y="3cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="3cm" width="1cm" height="1cm"/>
  </g>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm"
        fill="none" stroke="blue" stroke-width=".02cm"/>
</svg>

View this example as SVG (SVG-enabled browsers only)

A g element can contain other g elements nested within it, to an arbitrary depth.

4.2.2. The ‘g’ element

g
Categories:
Container element, renderable element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
DOM Interfaces:

4.3. Unknown elements

SVG 2 Requirement: Have unknown elements treated as g for the purpose of rendering.
Resolution: Accept having unknown elements treated as ‘g’ for the purpose of rendering.
Purpose: To allow fallbacks without the use of switch, and to align with the behavior of unknown elements in HTML.
Owner: Nobody (no action)
Status:
unknown
Categories:
None
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

The SVGUnknownElement interface must be used for elements in the SVG namespace that are not defined by this specification.

Known elements in the SVG namespace that occur in places where SVG's content model doesn't explicitly allow it must not render.

Unknown elements in the SVG namespace render as if the unknown element was a g element.

Known and unknown elements in other namespaces that occur as a child of any SVG element except foreignObject, must not render unless explicitly stated otherwise in this specification.

Consequently, in the following example:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 200">
  <rect x=".1" y=".1" width="699.8" height="199.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <mysteryElement>
    <path d="M0 0h600v200h-600z" fill="darkkhaki"/>
  </mysteryElement>
  <hideElement xmlns="http://www.example.com/invisibleML">
    nothing to see here
    <path d="M0 0h300v100h-300z" fill="whitesmoke"/>
  </hideElement>
  <text y="2em" font-size="20"><text>This text must not be visible</text></text>
  <linearGradient>
    <gradientExtension>
      <path d="M300 0h100v200h-100z" fill="fuchsia"/>
    </gradientExtension>
  </linearGradient>
  <div xmlns="http://www.w3.org/1999/xhtml">This must not be visible</div>
</svg>

View this example as SVG (SVG-enabled browsers only)

Do we need to mention anything about attributes, properties and such on SVGUnknownElements?

Should SVGUnknownElement be a container element?

4.4.1. Overview

SVG allows graphical objects to be defined for later reuse. To do this, it makes extensive use of URL references [RFC3987] to these 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)"/>

Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.

It is recommended that, wherever possible, referenced elements be defined inside of a defs element. Among the elements that are always referenced: clipPath, cursor, filter, linearGradient, marker, mask, pattern, radialGradient and symbol.

4.4.2. The ‘defs’ element

defs
Categories:
Container element, never-rendered element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
DOM Interfaces:

The defs element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a defs.

The content model for defs is the same as for the g element; thus, any element that can be a child of a g can also be a child of a defs, and vice versa.

Elements that are descendants of a defs are not rendered directly; they are prevented from becoming part of the rendering tree just as if the defs element were a g element and the display property were set to none. Note, however, that the descendants of a defs are always present in the source tree and thus can always be referenced by other elements; thus, the value of the display property on the defs element or any of its descendants does not prevent those elements from being referenced by other elements.

4.5. The ‘desc’ and ‘title’ elements

4.5.1. Definition

descriptive element
An element which provides supplementary descriptive information about its parent. Specifically, the following elements are descriptive elements: desc, metadata and title.
desc
Categories:
Descriptive element, never-rendered element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:
title
Categories:
Descriptive element, never-rendered element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

The attribute lang added to allow internationalization of the desc and title elements.

New in SVG 2. Adding 'lang' resolved at Rigi Kaltbad face-to-face. Removed text that limited number of 'desc' and 'title' elements. Status: Done.

Any container element or graphics element in an SVG document can have zero or more desc and/or title elements as children, whose content is text. desc and title elements are not visually rendered as part of the graphics.

Multiple sibling desc or title elements must have different lang attributes. The element whose lang attribute best matches the language set by the user agent will be used as the title or desc. If no match exists, the first element must be used. If multiple equally valid matches exist, the first match is used.

The use of more than one title or desc element to provide localised information is at risk, with no known implementations.

The title child element represents a short text alternative for the element.

On a link, this could be the title or a description of the target resource; on an image or drawing object, it could be the image credit or short description of the object; on interactive content, it could be a label for, or instructions for, use of the element; and so forth.

Interactive User agents commonly render title elements as a tooltip on hovering the parent element.

User agents should make title and desc elements available to platform accessibility APIs as per SVG-AAM.

Authors should not provide both a visible label for a drawing element by using a text element, and a title element, as they will be both presented, redundantly, to users.

The desc element represents more detailed textual information for the element such as a description. This is typically exposed to assistive technologies to provide more detailed information, such as help information about the element.

Authors should provide a title child element to the outermost svg element within a stand-alone SVG document. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesn't provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, user agents should always make the content of the ‘title’ child element to the outermost svg element available to users.

Unlike the desc element, authors also have the ability to associate more detailed information with content that includes visible text. This can be achieved by applying aria-describedby to the element, or container of elements being described and passing an ID reference to content that includes text that describes the element in question. However, if the text describing the object is hidden the text within the description would be exposed to assistive technologies as detailed text information, similar to a descendant desc element. The aria-describedby attribute takes precedence over the child desc when providing a description, consequently authors should only use aria-describedby when an element is described by visible text on the screen, otherwise the use of a child desc is preferred.

Alternate presentations are possible, both visual and aural, which display the desc and title elements but do not display path elements or other graphics elements. For deep hierarchies, and for following use element references, it is sometimes desirable to allow the user to control how deep they drill down into descriptive text.

The following is an example. In typical operation, the SVG user agent would not render the desc and title elements but would render the remaining contents of the g element.

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 400 300">
  <g>
    <title>Company sales by region</title>
    <title lang="fr">Chiffre d'affaires par région</title>
    <desc>Bar chart which shows company sales by region.</desc>
    <desc lang="fr">Graphique illustrant les ventes par région.</desc>
    <line x1="30" y1="10" x2="380" y2="270"/>
  </g>
</svg>

Description and title elements can contain marked-up text from other namespaces.

We should say what purpose including other-namespaced markup in title and desc has. If it is just that these are basically metadata extension points for other profiles or uses of SVG, then we should say that.

4.6. The ‘metadata’ element

Metadata which is included with SVG content should be specified within metadata elements. The contents of the metadata should be elements from other XML namespaces, with these elements from these namespaces expressed in a manner conforming with the Namespaces in XML Recommendation [XML-NS].

SVG 2 removes the recommendation to structure metadata elements in any particular way.

metadata
Categories:
Descriptive element, never-rendered element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

Here is an example of how metadata can be included in an SVG document. The example uses the Dublin Core version 1.1 schema. (Other XML-compatible metadata languages, including ones not based on RDF, can be used also.)

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
    xmlns = 'http://www.w3.org/2000/svg'>
    <desc xmlns:myfoo="http://example.org/myfoo">
      <myfoo:title>This is a financial report</myfoo:title>
      <myfoo:descr>The global description uses markup from the
        <myfoo:emph>myfoo</myfoo:emph> namespace.</myfoo:descr>
      <myfoo:scene><myfoo:what>widget $growth</myfoo:what>
      <myfoo:contains>$three $graph-bar</myfoo:contains>
        <myfoo:when>1998 $through 2000</myfoo:when> </myfoo:scene>
   </desc>
    <metadata>
      <rdf:RDF
           xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
           xmlns:dc = "http://purl.org/dc/elements/1.1/" >
        <rdf:Description about="http://example.org/myfoo"
             dc:title="MyFoo Financial Report"
             dc:description="$three $bar $thousands $dollars $from 1998 $through 2000"
             dc:publisher="Example Organization"
             dc:date="2000-04-11"
             dc:format="image/svg+xml"
             dc:language="en" >
          <dc:creator>
            <rdf:Bag>
              <rdf:li>Irving Bird</rdf:li>
              <rdf:li>Mary Lambert</rdf:li>
            </rdf:Bag>
          </dc:creator>
        </rdf:Description>
      </rdf:RDF>
    </metadata>
</svg>

4.7. The ‘symbol’ element

symbol
Categories:
Container element, never-rendered element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
DOM Interfaces:

4.7.1. Attributes

Name Value Initial value Animatable
refX <length> | left | center | right 0 yes
refY <length> | top | center | bottom 0 yes

New in SVG 2. Added to make it easier to align symbols to a particular point, as is often done in maps. Similar to the matching attributes on marker.

Add refX/refY to symbol element. Resolved at Leipzig F2F. Status: Done.

We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'. Status: Done.

The refX and refY attributes define the reference point of the symbol which is to be placed exactly at the symbol's position as defined by the use element. They are interpreted as being in the coordinate system of the symbol contents, after application of the viewBox and preserveAspectRatio attributes.

4.7.2. Notes on symbols

The symbol element is used to define graphical template objects which can be instantiated by a use element but are not rendered directly.

The use of symbol elements for graphics that are used multiple times in the same document adds structure and semantics. Closely related to the symbol element are the marker and pattern elements.

The user agent style sheet sets the overflow property for symbol elements to hidden, which causes a rectangular clipping path to be created at the bounds of symbol's SVG viewport. Unless the overflow property is overridden, any graphics within the symbol which goes outside of the symbol's SVG viewport will be clipped.

symbol elements must never be rendered directly; their only usage is as something that can be referenced using the use element. The display property does not apply to the symbol element; thus, symbol elements are not directly rendered even if the display property is set to a value other than none, and symbol elements are available for referencing even when the display property on the symbol element or any of its ancestors is set to none.

4.8. The ‘use’ element

SVG 2 Requirement: Allow use to reference an external document's root element by omitting the fragment.
Resolution: We will relax referencing requirements to particular elements to allow dropping fragments to mean referencing root element, where it makes sense, such as with use, in SVG 2.
Purpose: To avoid requiring authors to modify the referenced document to add an ID to the root element.
Owner: Cameron (ACTION-3417)
Status: Done
use
Categories:
Graphics element, graphics referencing element, renderable element, structural element, structurally external element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script
Attributes:
DOM Interfaces:

The use element references another element and indicates that a copy of the graphical contents of that element is rendered at that given point in the document. These re-used graphics inherit styles from the use element and in certain cases can be re-sized. However, they remain linked to the referenced source and reflect DOM mutations, animations, and style changes in the original.

4.8.1. Attributes

Name Value Initial value Animatable
x, y <length> 0 yes
width, height <length> (see below) yes

The x, y, width and height attributes specify the positioning of the referenced element. The width and height attributes have different initial values depending on the type of the referenced element:

svg
The initial values are the width and height presentation attribute values from the referenced svg element.
anything else
The initial values are '100%'.

A negative value for width or height is an error (see Error processing). If width or height is zero then rendering of the use element is disabled.

Name Value Initial value Animatable
href URL [URL] (none) yes

An URL reference to the element/fragment within an SVG document to be cloned for rendering.

Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

4.8.2. Re-usable graphics and the shadow tree

The graphical contents are any svg, symbol, g, graphics element or other use elements, that a use element references.

The use element can reference an entire SVG document by specifying an href value without a fragment. Such references are taken to be referring to the root element of the referenced document.

New in SVG 2. This allows an entire SVG document to be referenced without having to ensure that it has an ID on its root element.

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.

The non-exposed DOM tree must be created even if 'display: none' is set on the use element. Note that script elements that get conceptually cloned into the non-exposed DOM tree do not execute again, and audio and video elements that may play audio must only do so if the use element is rendered.

A use element has the same visual effect as if the use element were replaced by the following generated content:

Except that the replaced content shouldn't affect how styles are matched.

In the generated content, the use will be replaced by g, where all attributes from the use element except for x, y, width, height, href and xlink:href are transferred to the generated g element. An additional transformation translate(x,y) is appended to the end (i.e., right-side) of the transform property on the generated g, where x and y represent the values of the x and y attributes on the use element.

The element referenced by use may be in a separate document. However, this specification does not define how or if the user agent will process stylesheets in that document, or what SVG viewport will be used for resolving percentages and media queries in such documents, if animations run in the separate document and which document controls the animation timeline. Script elements in the resource document must not be executed, and the corresponding conceptually cloned script elements must also not execute.

When re-using external assets, therefore, authors are advised not to include any scripts in the external file and to use inline styles or presentation attributes only. Percentage lengths should only be used if the re-used assets define their own SVG viewport (i.e., if the re-used element is an svg or symbol). Declarative animations in external assets should not be used.

User agents may restrict restrict external resource documents for security reasons. In particular, this specification does not allow cross-origin resource requests in use. A future version of this or another specification may provide a method of securely enabling cross-origin re-use of assets.

When a use references another element which is another use or whose content contains a use element, then the deep cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an error, as described in References and the ‘defs’ element.

4.8.3. Layout

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.

4.8.4. Style Inheritance

The conceptual deep cloning of the referenced element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS21], chapter 6) on the referenced element and its contents. CSS2 selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS2 selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.

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 the referenced element's original parents.

Note that specifying 'visibility:hidden' on a use element does not guarantee that the referenced content will not be rendered. If the use element specifies 'visibility:hidden' and the element it references specifies 'visibility:hidden' or 'visibility:inherit', then that one element will be hidden. However, if the referenced element instead specifies 'visibility:visible', then that element will be visible even if the use element specifies 'visibility:hidden'.

Animations on a referenced element will cause the instances to also be animated.

For user agents that support Styling with CSS, the generated g element carries along with it the "cascaded" property values on the use element which result from the CSS cascade ([CSS21], chapter 6). Additionally, the copy (deep clone) of the referenced resource carries along with it the "cascaded" property values resulting from the CSS cascade on the original (i.e., referenced) elements. Thus, the result of various CSS selectors in combination with the class and style attributes are, in effect, replaced by the functional equivalent of a style attribute in the generated content which conveys the "cascaded" property values.

Example Use01 below has a simple use on a rect.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Example Use01 - Simple case of 'use' on a 'rect'</desc>
  <defs>
    <rect id="MyRect" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use x="20" y="10" href="#MyRect" />
</svg>
Example Use01 — Simple case of 'use' on a 'rect'

Example Use01

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use01-GeneratedContent - Simple case of 'use' on a 'rect'</desc>
  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,10)">
    <rect width="60" height="10"/>
  </g>
  <!-- End of generated content -->

</svg>

View this example as SVG (SVG-enabled browsers only)

Example Use02 below has a use on a symbol.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Example Use02 - 'use' on a 'symbol'</desc>
  <defs>
    <symbol id="MySymbol" viewBox="0 0 20 20">
      <desc>MySymbol - four rectangles in a grid</desc>
      <rect x="1" y="1" width="8" height="8"/>
      <rect x="11" y="1" width="8" height="8"/>
      <rect x="1" y="11" width="8" height="8"/>
      <rect x="11" y="11" width="8" height="8"/>
    </symbol>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use x="45" y="10" width="10" height="10" href="#MySymbol" />
</svg>
Example Use02 — 'use' on a 'symbol'

Example Use02

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use02-GeneratedContent - 'use' on a 'symbol'</desc>

  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(45, 10)" >
    <!-- Start of referenced 'symbol'. 'symbol' replaced by 'svg',
         with x,y,width,height=0,0,100%,100% -->
    <svg width="10" height="10" 
         viewBox="0 0 20 20">
      <rect x="1" y="1" width="8" height="8"/>
      <rect x="11" y="1" width="8" height="8"/>
      <rect x="1" y="11" width="8" height="8"/>
      <rect x="11" y="11" width="8" height="8"/>
    </svg>
    <!-- End of referenced symbol -->
  </g>
  <!-- End of generated content -->

</svg>

View this example as SVG (SVG-enabled browsers only)

Example Use03 illustrates what happens when a use has a transform property.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Example Use03 - 'use' with a 'transform' attribute</desc>
  <defs>
    <rect id="MyRect" x="0" y="0" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use href="#MyRect"
       transform="translate(20,2.5) rotate(10)" />
</svg>
Example Use03 — 'use' with a 'transform' property

Example Use03

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use03-GeneratedContent - 'use' with a 'transform' attribute</desc>

  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,2.5) rotate(10)">
    <rect x="0" y="0" width="60" height="10"/>
  </g>
  <!-- End of generated content -->

</svg>

View this example as SVG (SVG-enabled browsers only)

Example Use04 illustrates a use element with various methods of applying CSS styling.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3cm" viewBox="0 0 1200 300"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Example Use04 - 'use' with CSS styling</desc>
  <defs style=" /* rule 9 */ stroke-miterlimit: 10" >
    <path id="MyPath" d="M300 50 L900 50 L900 250 L300 250"
                     class="MyPathClass"
                     style=" /* rule 10 */ stroke-dasharray:300,100" />
  </defs>
  <style type="text/css">
    <![CDATA[
      /* rule 1 */ #MyUse { fill: blue }
      /* rule 2 */ #MyPath { stroke: red }
      /* rule 3 */ use { fill-opacity: .5 }
      /* rule 4 */ path { stroke-opacity: .5 }
      /* rule 5 */ .MyUseClass { stroke-linecap: round }
      /* rule 6 */ .MyPathClass { stroke-linejoin: bevel }
      /* rule 7 */ use > path { shape-rendering: optimizeQuality }
      /* rule 8 */ g > path { visibility: hidden }
    ]]>
  </style>

  <rect x="0" y="0" width="1200" height="300"
         style="fill:none; stroke:blue; stroke-width:3"/>
  <g style=" /* rule 11 */ stroke-width:40">
    <use id="MyUse" href="#MyPath"
         class="MyUseClass"
         style="/* rule 12 */ stroke-dashoffset:50" />
  </g>
</svg>
Example Use04 — 'use' with CSS styling

Example Use04

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document. Observe that some of the style rules above apply to the generated content (i.e., rules 1-6, 10-12), whereas others do not (i.e., rules 7-9). The rules which do not affect the generated content are:

In the generated content below, the selectors that yield a match have been transferred into inline style attributes for illustrative purposes.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3cm" viewBox="0 0 1200 300"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use04-GeneratedContent - 'use' with a 'transform' attribute</desc>

  <!-- 'style' and 'defs' sections left out -->

  <rect x="0" y="0" width="1200" height="300"
         style="fill:none; stroke:blue; stroke-width:3"/>
  <g style="/* rule 11 */ stroke-width:40">

    <!-- Start of generated content. Replaces 'use' -->
    <g style="/* rule 1 */ fill:blue;
                 /* rule 3 */ fill-opacity:.5;
                 /* rule 5 */ stroke-linecap:round;
                 /* rule 12 */ stroke-dashoffset:50" >
      <path d="M300 50 L900 50 L900 250 L300 250"
            style="/* rule 2 */ stroke:red; 
                   /* rule 4 */ stroke-opacity:.5; 
                   /* rule 6 */ stroke-linejoin: bevel; 
                   /* rule 10 */ stroke-dasharray:300,100" />
    </g> 
    <!-- End of generated content -->

  </g>
</svg>

View this example as SVG (SVG-enabled browsers only)

4.8.5. Event handling

If event attributes are assigned to referenced elements, then the actual target for the event will be the element within the "instance tree" corresponding to the given referenced element.

The event handling for the non-exposed tree works as if the referenced element had been textually included as a deeply cloned child of the use element, and events are dispatched according to the shadow tree event dispatching algorithm [SHADOWDOM]. The event's target and currentTarget attributes are set to the instance tree element that corresponds to the target and current target elements in the referenced subtree. An event propagates through the exposed and non-exposed portions of the tree in the same manner as it would in the regular document tree: first going from the root element to the use element and then through non-exposed tree elements in the capture phase, followed by the target phase at the target of the event, then bubbling back through non-exposed tree to the use element and then back through regular tree to the root element in bubbling phase. In order to maintain encapsulation events must use the event retargeting algorithm [SHADOWDOM] when crossing from a non-exposed tree to the regular tree.

We should define the behavior of use in terms of Web Components. See ACTION-3729 (Tab) Github Issue #99

4.9. Conditional processing

4.9.1. Conditional processing overview

SVG contains a switch element along with attributes requiredExtensions and systemLanguage to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.

Attributes requiredExtensions and systemLanguage act as tests and evaluate to either true or false. The switch renders the first of its children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.

Similar to the display property, conditional processing attributes only affect the direct rendering of elements and do not prevent elements from being successfully referenced by other elements (such as via a use).

In consequence:

4.9.2. Definitions

conditional processing attribute
A conditional processing attribute is one that controls whether or not the element on which it appears is processed. Most elements, but not all, may have conditional processing attributes specified on them. See Conditional processing for details. The conditional processing attributes defined in SVG 1.1 are requiredExtensions and systemLanguage.

4.9.3. The ‘switch’ element

switch
Categories:
Container element, renderable element
Content model:
Any number of the following elements, in any order:a, clipPath, foreignObject, g, image, marker, mask, script, svg, switch, text, use
Attributes:
DOM Interfaces:

The switch element evaluates the requiredExtensions and systemLanguage attributes on its direct child elements in order, and then processes and renders the first child for which these attributes evaluate to true. All others will be bypassed and therefore not rendered. If the child element is a container element such as a g, then the entire subtree is either processed/rendered or bypassed/not rendered.

Note that the values of properties display and visibility have no effect on switch element processing. In particular, setting display to none on a child of a switch element has no effect on true/false testing associated with switch element processing.

The switch element does not affect the processing of script and style elements.

For more information and an example, see Embedding foreign object types.

4.9.4. The ‘requiredExtensions’ attribute

The requiredExtensions attribute defines a list of required language extensions. Language extensions are capabilities within a user agent that go beyond the feature set defined in this specification. Each extension is identified by an URL reference.

Name Value Initial value Animatable
requiredExtensions set of space-separated tokens [HTML] (none) no

The value is a list of URL references which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.

If a given URL reference contains white space within itself, that white space must be escaped.

If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute requiredExtensions, the attribute evaluates to "false".

requiredExtensions is often used in conjunction with the switch element. If the requiredExtensions is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

The URL names for the extension should include versioning information, such as "http://example.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.

4.9.5. The ‘systemLanguage’ attribute

Name Value Initial value Animatable
systemLanguage set of comma-separated tokens [HTML] (none) no

The value is a set of comma-separated tokens, each of which must be a Language-Tag value, as defined in BCP 47 [BCP47].

Evaluates to "true" if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-".

Evaluates to "false" otherwise.

If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute systemLanguage, the attribute evaluates to "false".

Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.

The prefix rule simply allows the use of prefix tags if this is the case.

Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.

Multiple languages may be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:

<text systemLanguage="mi, en"><!-- content goes here --></text>

However, just because multiple languages are present within the object on which the systemLanguage test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the systemLanguage test attribute should only include "en".

Authoring note: Authors should realize that if several alternative language objects are enclosed in a switch, and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a switch which is acceptable in all cases.

systemLanguage is often used in conjunction with the switch element. If the systemLanguage is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

4.10. HTML metadata elements

For user agents that support HTML, the following HTML elements (in the HTML namespace) must be supported in SVG documents:

Note that the base element will affect all URL values in the document, including e.g paint server references.

4.11. Common attributes

4.11.1. Definitions

core attributes
The core attributes are those attributes that can be specified on any SVG element. This includes common attributes, and styling attributes. The core attributes are id, tabindex, lang and xml:space, class and style, and all custom data attributes.

4.11.2. Attributes common to all elements: ‘id’

The id attribute is available on all SVG elements:

Name Value Initial value Animatable
id (see below) (none) no

Must reflect the element's ID [DOM4]. The id attribute must be any value other than the empty string.

4.11.3. The ‘lang’ and ‘xml:lang’ attributes

The ‘lang’ attribute (in no namespace) specifies the primary language for the element's contents and for any of the element's attributes that contain text.

The ‘lang’ attribute in the XML namespace is defined in XML [XML10].

If these attributes are omitted from an element, then the language of this element is the same as the language of its parent element, if any.

The ‘lang’ attribute in the XML namespace may be used on SVG elements in XML documents. If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the XML namespace are specified on the same element, they must have exactly the same value when compared in an ASCII case-insensitive manner.

If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the XML namespace are set on an element, user agents must use the ‘lang’ attribute in the XML namespace, and the ‘lang’ attribute in no namespace must be ignored for the purposes of determining the element's language.

Name Value Initial value Animatable
lang Language-Tag [ABNF] (none) no

The ‘lang’ attribute specifies the primary language for the element's contents and for any of the element's attributes that contain text. Its value must be a valid BCP 47 language tag, or the empty string. Setting the attribute to the empty string indicates that the primary language is unknown. [BCP47].

4.11.4. The ‘xml:space’ attribute

SVG 2 Requirement: Deprecate the use of ‘xml:space’ to affect text layout and use the ‘white-space’ property instead.
Resolution: We drop xml:space from SVG 2 and remove the relating tests from the SVG 1.1. test suite.
Purpose: To align with CSS.
Owner: Chris (ACTION-3004, done; and ACTION-3005, done)
Status Done.
Name Value Initial value Animatable
xml:space (see below) default no

Deprecated XML attribute to specify whether white space is preserved in character data. The only possible values are the strings 'default' and 'preserve', without white space. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10] and to the discussion white space handling in SVG.

New content should use the white-space property instead.

4.11.5. The ‘tabindex’ attribute

Name Value Initial value Animatable
tabindex valid integer [HTML] (none) no

This content attribute allows authors to control whether an element is focusable, whether it is supposed to be reachable using sequential focus navigation, and what is to be the relative order of the element for the purposes of sequential focus navigation.

The name "tab index" comes from the common use of the "tab" key to navigate through the focusable elements. The term "tabbing" refers to moving forward through the focusable elements that can be reached using sequential focus navigation.

4.11.6. The ‘data-*’ attributes

All SVG elements support custom data attributes, which are those in no namespace whose names begin with the string "data-". See the requirements for custom data attributes in the HTML specification.

4.12. WAI-ARIA attributes

4.12.1. Definitions

ARIA attributes
These are the attributes used consisting of WAI-ARIA states and properties as well as the role attribute whose values are defined defined in WAI-ARIA. See the WAI-ARIA Definition of Roles, the WAI-ARIA Graphics Module Graphics Roles, and the WAI-ARIA Supported States and Properties. The aria attributes are aria-activedescendant, role, aria-autocomplete, aria-busy, aria-checked, aria-colcount, aria-colindex, aria-colspan, aria-controls, aria-current, aria-describedby, aria-details, aria-disabled, aria-dropeffect, aria-errormessage, aria-expanded, aria-flowto, aria-grabbed, aria-haspopup, aria-hidden, aria-invalid, aria-label, aria-labelledby, aria-level, aria-atomic, aria-modal, aria-multiline, aria-multiselectable, aria-orientation, aria-owns, aria-placeholder, aria-posinset, aria-pressed, aria-readonly, aria-relevant, aria-required, aria-roledescription, aria-rowcount, aria-rowindex, aria-rowspan, aria-selected, aria-setsize, aria-sort, aria-valuemax, aria-valuemin, aria-valuenow, aria-valuetext and aria-live.

Note that the above list ARIA attributes is likely to change in an upcoming version of the SVG Accessibility API mappings specification..

4.12.2. Role attribute

SVG elements having native semantics that are not limited to presentation (having "no role"), may have an ARIA role attribute specified. The attribute, if specified, must have a value that is a set of space-separated tokens representing the various WAI-ARIA roles that the element belongs to. These tokens are role values defined in Definition of Roles ([ARIA], section 5.4) and Graphics Roles ([ARIA-GRAPHICS], section 4).

The WAI-ARIA role that an SVG element has assigned to it is the first non-abstract role found in the list of values generated when the role attribute is split on spaces.

Name Value Initial value Animatable
role set of space-separated tokens [HTML] (see below) no

The role attribute must be a set of space-separated tokens having values defined in Definition of Roles ([ARIA], section 5.4).

The role value is a set of white-space separated machine-extractable semantic information used to define the purpose of the element.

The initial value for the role attribute, for each SVG element, is the corresponding default implied ARIA semantic for SVG elements.

4.12.3. State and property attributes (all aria- attributes)

SVG elements having native semantics that are not limited to presentation (having "no role"), may have an may have WAI-ARIA state and property attributes specified. These attributes are defined by ARIA in Definitions of States and Properties (all aria-* attributes) ([ARIA], section 6.6).

These attributes, if specified, must have a value that is the WAI-ARIA value type in the "Value" field of the definition for the state or property, mapped to the appropriate SVG value type according to Mapping WAI-ARIA Value types to languages using the SVG mapping ([ARIA], section 10.2).

WAI-ARIA State and Property attributes can be used on any element. They are not always meaningful, however, and in such cases user agents might not perform any processing aside from including them in the DOM. State and property attributes are processed according to the ARIA and SVG Accessibility API Mappings specification specifications. [ARIA] [SVG-AAM]

4.12.4. Implicit ARIA Semantics

The following table defines the default implicit ARIA semantics that apply to SVG elements. Each language feature (element) in a cell in the first column implies the ARIA semantics (role, states, and/or properties) given in the cell in the second column of the same row. The third column defines restrictions as to what WAI-ARIA semantic (role, state, or property) may or may not apply.

Language featureDefault implied ARIA semanticsRestrictions
a link role no restrictions
audio group role If specified, role must be application
canvas group role no restrictions
circle none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
clipPath none no role may be applied
cursor none no restrictions
defs none no role may be applied
desc none no role may be applied
ellipse none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
feBlend none no role may be applied
feColorMatrix none no role may be applied
feComponentTransfer none no role may be applied
feComposite none no role may be applied
feConvolveMatrix none no role may be applied
feDiffuseLighting none no role may be applied
feDisplacementMap none no role may be applied
feDistantLight none no role may be applied
feDropShadow none no role may be applied
feFlood none no role may be applied
feFuncA none no role may be applied
feFuncB none no role may be applied
feFuncG none no role may be applied
feFuncR none no role may be applied
feGaussianBlur none no role may be applied
feImage none no role may be applied
feMerge none no role may be applied
feMergeNode none no role may be applied
feMorphology none no role may be applied
feOffset none no role may be applied
fePointLight none no role may be applied
feSpecularLighting none no role may be applied
feSpotLight none no role may be applied
feTile none no role may be applied
feTurbulence none no role may be applied
filter none no role may be applied
foreignObject none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
g none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
hatch none no role may be applied
hatchpath none no role may be applied
iframe no role If Specified, role must be either application, document, or img roles
image img role no restrictions
line none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
linearGradient none no role may be applied
marker none no role may be applied
mask none no role may be applied
mesh none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, img role no restrictions
meshpatch none no role may be applied
meshrow none no role may be applied
metadata none no role may be applied
mpath none no role may be applied
path none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
pattern none no role may be applied
polygon none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
polyline none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
radialGradient none no role may be applied
rect none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
script none no role may be applied
solidcolor none no role may be applied
stop none no role may be applied
style none no role may be applied
svg graphics-doc role no restrictions
switch none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
symbol none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
text group role no restrictions
textPath group role no restrictions
title none no role may be applied
tspan none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions
use none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, graphics-symbol role no restrictions
video group role If specified, role must be application
view none role provided no associated title element, desc element, aria-label attribute, aria-labelledby attribute, aria-describedby attribute; or tabindex attribute; otherwise, group role no restrictions

4.13. DOM interfaces

4.13.1. Extensions to the Document interface

The DOM Core specification defines a Document interface, which this specification extends.

In the case where an SVG document is embedded by reference, such as when an HTML document has an ‘object’ element whose ‘data’ attribute references an SVG document (i.e., a document whose MIME type is "image/svg+xml" and whose root element is thus an svg element), there will exist two distinct DOM hierarchies. The first DOM hierarchy will be for the referencing document (e.g., an XHTML document). The second DOM hierarchy will be for the referenced SVG document.

partial interface Document {
  readonly attribute SVGSVGElement rootElement;
};

The rootElement IDL attribute represents the root svg element. On getting rootElement, the root element of the document is returned, if it is an svg element, or null otherwise.

This attribute is deprecated, and may be removed in a future SVG specification. Authors are encouraged to use the documentElement attribute on Document instead.

SVG implementations that implement HTML must support the HTML extensions to the document interface. Other SVG implementations must support the following IDL fragment.

// must only be implemented in certain implementations
partial interface Document {
  readonly attribute DOMString title;
  readonly attribute DOMString referrer;
  readonly attribute DOMString domain;
  readonly attribute Element? activeElement;
};

The title, referrer, domain and activeElement IDL attributes must behave the same as the corresponding IDL attributes defined in HTML.

4.13.2. Interface SVGSVGElement

An SVGSVGElement object represents an svg element in the DOM. The SVGSVGElement interface also contains miscellaneous utility methods, such as data type object factory methods.

An SVGSVGElement object maintains an internal DOMPoint object, called its current translate point object, which is the object returned from the currentTranslate IDL attribute.

interface SVGSVGElement : SVGGraphicsElement {

  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;

  attribute float currentScale;
  [SameObject] readonly attribute DOMPointReadOnly currentTranslate;

  NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement);
  NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement);
  boolean checkIntersection(SVGElement element, DOMRectReadOnly rect);
  boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect);

  void deselectAll();

  SVGNumber createSVGNumber();
  SVGLength createSVGLength();
  SVGAngle createSVGAngle();
  DOMPoint createSVGPoint();
  DOMMatrix createSVGMatrix();
  DOMRect createSVGRect();
  SVGTransform createSVGTransform();
  SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);

  // Deprecated methods that have no effect when called,
  // but which are kept for compatibility reasons.
  unsigned long suspendRedraw(unsigned long maxWaitMilliseconds);
  void unsuspendRedraw(unsigned long suspendHandleID);
  void unsuspendRedrawAll();
  void forceRedraw();
};

SVGSVGElement implements SVGFitToViewBox;
SVGSVGElement implements SVGZoomAndPan;
SVGSVGElement implements WindowEventHandlers;

The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.

The currentScale and currentTranslate IDL attributes represent the transform applied to the document in response to user magnification and panning operations, as described under Magnification and panning.

The document's magnification and panning transform is a 2x3 matrix of the form [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]. The value of the transform property does not affect currentScale or currentTranslate.

On getting currentScale, the following steps are run:

  1. If the current svg element is not the outermost svg element, then return 1.
  2. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
  3. Return a.

On setting currentScale, the following steps are run:

  1. If the current svg element is not the outermost svg element, then return.
  2. Let scale be the value being assigned to currentScale.
  3. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
  4. Set the document's magnification and panning transform to [scale 0 0 scale e f].

On getting currentTranslate, the SVGSVGElement object's current translate point object is returned. This object represents the current translation for the svg element. A current translate point object must be read only when its svg element is not the outermost svg element, and writable otherwise.

See the rules for assigning to a DOMPoint for how modifying the current translate point object affects the document's magnification and panning transform.

Whenever the document's magnification and panning transform changes in response to user interaction or whenever the outermost svg element changes, the following steps are run:

  1. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
  2. Let element be the outermost svg element.
  3. Update the x and y components of element's current translate point object to e and f, respectively.

Running these steps when the outermost svg element changes will ensure that if the document element is replaced with a different svg element, that its currentTranslate will be immediately updated to reflect the translation component of the document's magnification and panning transform.

Whenever an svg element is no longer outermost svg element, the x and y components of its current translate point object must be set to 0.

Note that the value of the zoomAndPan attribute on the outermost svg element only controls whether the document's magnification and panning transform can be updated through user interaction. Regardless of the value of that attribute, the current scale and translation can be changed by modifying currentScale and currentTranslate.

The suspendRedraw, unsuspendRedraw, unsuspendRedrawAll and forceRedraw methods are all deprecated and defined to have no effect. When the suspendRedraw method is called, it must return 1.

The getIntersectionList, getEnclosureList, checkIntersection and checkEnclosure methods are used to perform geometry operations on graphics elements to find those whose (or check whether their) graphical content lies partially or completely within a given rectangle.

To find the intersecting or enclosed descendants of a given element element with a given rectangle rectangle using ancestor as the element in whose coordinate space rectangle is to be interpreted, the following steps are run:

  1. Let result be an initially empty list.
  2. If element is not displayed, due to having a display value of none or being in a subtree that has failing conditional processing attributes or a failing branch of a switch, then return result.
  3. For each child element child of element, in document order:
    1. If child is an svg or g element, then:
      1. Let descendants be the result of finding the intersecting (or enclosed) descendants of child with rectangle in ancestor's coordinate space.
      2. Append to result all the elements of descendants.
    2. Otherwise, if child is a use element, then:
      1. Let root be the root of the child's shadow tree.
      2. Let descendants be the result of finding the intersecting (or enclosed) descendants of child with rectangle in ancestor's coordinate space.
      3. If descendants is not empty, then append child to result.

        This means that although we look at the specific content referenced by the use element, we don't place the referencing content in the result list; only the use element itself is returned.

    3. Otherwise, if child is a graphics element, then:
      1. Let region be the shape in child's coordinate system that is sensitive to hit detection, taking into account the rules for interpreting child's pointer-events value.
      2. Transform region into ancestor's coordinate system.
      3. If we are finding intersecting descendants and region lies partially or fully within rectangle, then append child to result.
      4. Otherwise, we are finding enclosed descendants. If region lies fully within rectangle, then append child to result.
  4. Return result.

To find the non-container graphics elements within a given element element, the following steps are run:

  1. Let result be an initially empty list.
  2. If element is an svg or g element, then for each child element child of element, in document order:
    1. Let descendants be the result of finding the non-container graphics elements within child.
    2. Append to result all the elements of descendants.
  3. Otherwise, if element is a graphics element then append element to result.
  4. Return result.

When getIntersectionList(rect, referenceElement) or getEnclosureList(rect, referenceElement) is called, the following steps are run:

  1. Let descendants be a list, depending on what method we are in:
    getIntersectionList
    descendants is the result of finding the intersecting descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
    getEnclosureList
    descendants is the result of finding the enclosed descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
  2. If referenceElement is not null, then remove from descendants any element that does not have referenceElement as an ancestor.
  3. Return a static NodeList that contains all of the elements in descendants. ([DOM4], section 5.2.7)

When checkIntersection(element, rect) or checkEnclosure(element, rect) is called, the following steps are run:

  1. Let descendants be a list, depending on what method we are in:
    getIntersectionList
    descendants is the result of finding the intersecting descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
    getEnclosureList
    descendants is the result of finding the enclosed descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
  2. Let elements be the result of finding the non-container graphics elements within element.
  3. If elements is empty, then return false.
  4. If any element in elements is not also in descendants, then return false.
  5. Return true.

The deselectAll method is used to remove any selections from the document. When deselectAll() is called, all ranges from the document's selection are removed and the selection's direction is set to forwards. [DOM4][EDITING] This method is deprecated, as it duplicates functionality from the Selection API.

This is equivalent to calling document.getSelection().removeAllRanges() on the document that this svg element is in.

The createSVGNumber, createSVGLength, createSVGAngle, createSVGPoint, createSVGMatrix, createSVGRect and createSVGTransform methods are all factory functions used to create a new datatype object of a particular type. When one of these methods is called, a new object is returned according to the following table:

MethodObject and details
createSVGNumberA new, detached SVGNumber object whose value is 0.
createSVGLengthA new, detached SVGLength object whose value is the unitless <number> 0.
createSVGAngleA new, detached SVGAngle object whose value is the unitless <number> 0.
createSVGPointA new, detached DOMPoint object whose coordinates are all 0.
createSVGMatrixA new, detached DOMMatrix object representing the identity matrix.
createSVGRectA new, DOMRect object whose x, y, width and height are all 0.
createSVGTransformA new, detached SVGTransform object whose value is matrix(1, 0, 0, 1, 0, 0).

The createSVGPoint, createSVGMatrix and createSVGRect methods are all deprecated and kept only for compatibility with legacy content. Authors are encouraged to use the DOMPoint, DOMMatrix and DOMRect constructors instead.

The createSVGTransformFromMatrix method is used to create a new SVGTransform object from a matrix object. Its behavior is the same as the createSVGTransformFromMatrix method on SVGTransformList.

4.13.3. Interface SVGGElement

An SVGGElement object represents a g element in the DOM.

interface SVGGElement : SVGGraphicsElement {
};

4.13.4. Interface SVGUnknownElement

An SVGUnknownElement object represents an unknown element in the SVG namespace.

interface SVGUnknownElement : SVGGraphicsElement {
};

4.13.5. Interface SVGDefsElement

An SVGDefsElement object represents a defs element in the DOM.

interface SVGDefsElement : SVGGraphicsElement {
};

4.13.6. Interface SVGDescElement

An SVGDescElement object represents a desc element in the DOM.

interface SVGDescElement : SVGElement {
};

4.13.7. Interface SVGMetadataElement

An SVGMetadataElement object represents a metadata element in the DOM.

interface SVGMetadataElement : SVGElement {
};

4.13.8. Interface SVGTitleElement

An SVGTitleElement object represents a title element in the DOM.

interface SVGTitleElement : SVGElement {
};

4.13.9. Interface SVGSymbolElement

An SVGSymbolElement object represents a symbol element in the DOM.

interface SVGSymbolElement : SVGElement {
};

SVGSymbolElement implements SVGFitToViewBox;

4.13.10. Interface SVGUseElement

An SVGUseElement object represents a use element in the DOM.

interface SVGUseElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
};

SVGUseElement implements SVGURIReference;

The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.

4.13.11. Interface SVGSwitchElement

An SVGSwitchElement object represents a switch element in the DOM.

interface SVGSwitchElement : SVGGraphicsElement {
};

4.13.12. Interface GetSVGDocument

This interface provides access to an SVG document embedded by reference in another DOM-based language. The expectation is that the interface is implemented on DOM objects that allow such SVG document references.

This interface is deprecated and may be dropped from future versions of the SVG specification. To access the SVG document inside an ‘iframe’ or ‘object’ element, authors are suggested to use the contentDocument attribute on the HTMLIFrameElement or HTMLObjectElement interface, respectively.

The HTMLIFrameElement, HTMLEmbedElement and HTMLObjectElement interfaces all define their own getSVGDocument method, which provides access to the SVG document in the same way that the GetSVGDocument does. Those three interfaces therefore do not need to implement GetSVGDocument. Still, authors are strongly recommended to use contentDocument instead.

[NoInterfaceObject]
interface GetSVGDocument {
  Document getSVGDocument();
};

The getSVGDocument method is used to return a referenced SVG document. When getSVGDocument() is called, it must return the Document object referenced by the embedding element that implements the GetSVGDocument interface; if there is no document, null is returned.

Note that this does no check to see whether the referenced document is indeed an SVG document. Instead, any document is returned.

SVG 2 – 04 May 2016 TopContentsPreviousNextElementsAttributesProperties