[go: up one dir, main page]

Chapter 5: Document Structure

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

5.1.1. Overview

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.)

5.1.2. Namespace

When SVG is parsed as a XML, for compliance with the Namespaces in XML Recommendation [xml-names], 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-names].

5.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: foreignObject, image, script and use.
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. Howevere, an svg element that is a direct child of another SVG-namespaced element is not 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: circle, ellipse, foreignObject, image, line, path, polygon, polyline, rect, text, textPath and tspan.
graphics referencing element
A graphics element which uses a reference to a different document or element as the source of its graphical content. Specifically: image and use.

5.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, 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. In either case, a computed style of auto is treated equivalent to 100%.

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.

5.2. Grouping: the ‘g’ element

5.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.

5.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, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
DOM Interfaces:

5.3.1. Overview

SVG allows a graphical object to be defined for later reuse. To do this, SVG makes extensive use of the URL reference construct [rfc3987]. For example, to fill a rectangle with a linear gradient, a linearGradient element may be defined with an id property that may be referenced in the value for the rectangle's fill property, as in the following:

<linearGradient id="MyGradient">...</linearGradient>
<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, where possible, referenced elements be defined prior to the elements that use them, in document order. Collecting all referenced elements inside of a single defs element near the top of the file can make the markup easier to read and understand.

5.3.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, 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; the display value for the defs element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute. 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 does not prevent those elements from being referenced by other elements.

5.4. The ‘symbol’ element

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

A symbol establishes a nested coordinate system for the graphics it contains. When a symbol is instantiated as the referenced element of a use element, it is therefore rendered very similarly to a nested svg element.

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

The x, y, width, and height geometry properties have the same effect as on an svg element, when the symbol is instantiated by a use element. In particular, if width and height compute to auto (and are not over-ridden by values on the instantiating use element), then they will be treated as a value of 100%.

New in SVG 2. Allowing geometry properties to be specified on a symbol provides a more consistent rendering model, and allows authors to set a default size for each symbol (which may still be over-ridden by attributes on the use element).

5.4.1. Attributes

Name Value Initial value Animatable
refX <length> | left | center | right (none) yes
refY <length> | top | center | bottom (none) 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 x,y positioning coordinate, as defined by the cumulative effect of the x and y properties and any transformations on the symbol and its host use element.

Keyword values have the same meaning as for the refX and refY attributes on the marker element, resolving to 0%, 50%, or 100% in the applicable direction.

Unlike other positioning attributes, refX and refY are interpreted as being in the coordinate system of the symbol contents, after application of the viewBox and preserveAspectRatio attributes. If one or both of the attributes is not specified, no adjustment is made in the corresponding dimension, and the top or left side of the symbol's rectangular viewport region (regardless of the viewBox coordinates) is positioned at the x,y point.

For backwards compatibility, the behavior when refX and refY are not specified on a symbol is different from when they are specified with a value of 0, and therefore different from the behavior when equivalent attributes are not specified on a marker.

5.4.2. Notes on symbols

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; all three define a container of graphical content that can be rendered repeatedly at various positions and scales in the SVG. However, while re-used graphics in a pattern and marker provide a graphical effect on another element, the content in a symbol will be embedded as fully interactive content, within a use-element shadow tree.

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 user agent must set the display property on the symbol element to none, as part of the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

The generated instance of a symbol that is the direct referenced element of a use element must always have a computed value of inline for the display property. In other words, it must be rendered whenever the host use element is rendered. The user agent style sheet again defines this declaration to have importance over any other CSS rule or presentation attribute. Any other symbol that is cloned to create an element instance within the use-element shadow tree behaves as a symbol definition, and must not be rendered.

5.5. 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 referencing element, renderable element, structural element, structurally external element
Content model:
Any number of the following elements, in any order:clipPath, mask, script, style
Attributes:
Geometry properties:
DOM Interfaces:

The use element references another element, a copy of which is rendered in place of the use in the document. The referenced element may be a container element, in which case a copy of the complete SVG document subtree rooted at that element is used.

The cloned content inherits styles from the use element and can be the target of user events. However, these cloned element instances remain linked to the referenced source and reflect DOM mutations in the original. In addition, all style rules that apply in the scope of the referenced element also apply in the scope of the cloned shadow tree.

The x, y, width and height geometric properties specify the positioning of the referenced element. The width and height attributes only have an effect if the referenced element defines a viewport (i.e., if it is a svg or symbol); if so, a value other than auto for the use element overrides the value of the corresponding geometric property on that element.

A negative value for width or height is invalid and must be ignored. If width or height is zero, and the properties have an effect on the referenced element, then rendering of that element will be disabled.

The x and y properties affect the user coordinate system for the element. See the Layout section for implementation details.

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.

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.

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

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

User agents may 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 the href attribute is set (or, in the absence of an href attribute, an xlink:href attribute), the user agent must process the URL. The target element that results from URL processing is the referenced element of the use.

If the referenced element that results from resolving the URL is not an SVG element, then the reference is invalid and the use element is in error.

If the referenced element is a (shadow-including) ancestor of the use element, then this is an invalid circular reference and the use element is in error.

Otherwise, the user agent must generate a shadow tree of re-used graphics to render as the contents of the use element, as described in the next section, The use-element shadow tree.

A use that has an unresolved or invalid URL reference is not rendered. For the purpose of bounding box calculations, it is equivalent to an empty container element.

5.5.1. The use-element shadow tree

The re-used graphics generated by a use element are defined in terms of a shadow tree. In terms of interactivity and style inheritance, they are therefore quite different from other types of re-used graphics in SVG, such as pattern and marker content.

Elements in the shadow tree are rendered as if the use element was a container and they were its children. However, the SVG Document Object Model (DOM) only contains the use element and its attributes. The SVG DOM does not include the element instances as children of the use element.

User agents that support scripting and the document object model must implement the use-element shadow tree as described in this section and in conformance with the dom specification [dom], or its future replacement. In contrast, user agents that do not support the dynamic interactive processing mode may not need to implement all the details of the shadow DOM. However, all user agents must ensure that the layout and style inheritance for the re-used graphics and declarative animations if applicable, are rendered in the same way as if the shadow DOM was implemented.

The following definitions apply when discussing use elements and their shadow trees:

referenced element
The element specified by the href (or xlink:href) attribute on the use element, or the root element of a document referenced by that attribute if the URL provided does not include a target fragment that links to a specific element id.
referenced document subtree
referenced graphics
The referenced element, and all of its descendent nodes.
shadow root
A ShadowRoot object, a type of DocumentFragment node which is associated with a host Element, and which contains the content that will be used to render that host. A shadow root should be implemented in conformance with the dom specification [dom], or its future replacement.
shadow host
host
An element that has an associated shadow root; usage is consistent the definition of host in the DOM standard.
shadow tree
A node tree whose root is a shadow root; usage is consistent the definition of shadow tree in the DOM standard.
use-element shadow tree
A shadow tree whose host is a use element, which contains element instances generated by cloning the referenced graphics.
element instance
instance
An element in the use-element shadow tree, which is generated by cloning a corresponding element in the referenced document subtree.
instance root
The element instance for the referenced element; it is always a direct child of the use element's shadow root.
corresponding element
For each element instance, the element in the referenced document subtree from which it is cloned.
corresponding use element
For each element instance, the use element which causes it to be rendered in the document. This is the instance's shadow root's host use element if that element is not itself an element instance within a use element shadow tree, or is that element's corresponding use element otherwise, recursively exiting shadow trees as many times as necessary to reach a use element that was not itself generated as part of the shadow tree of another use element.

When the user agent successfully resolves a use element to identify a referenced element, the user agent must create a use-element shadow tree whose host is the use element itself. The shadow tree must be created even if the use element is not rendered because it is a descendent of a never-rendered element, because of conditional processing, or because of the display property being set to none on it or an ancestor element.

Each node in the shadow tree is an instance of a corresponding node from the referenced document subtree. The shadow nodes all descend from the instance root, which is the instance of the referenced element, and which itself is a direct child of the shadow root node.

The shadow tree is open (inspectable by script), but read-only. Any attempt to directly modify the elements, attributes, and other nodes in the shadow tree must throw a NoModificationAllowedError.

Within a use-element shadow tree, script elements are inert (do not execute).

Previous versions of SVG restricted the contents of the shadow tree to SVG graphics elements. This specification allows any valid SVG document subtree to be cloned. Cloning non-graphical content, however, will not usually have any visible effect.

If the referenced element is in an external file, then all URL references in attributes and style properties must be made absolute as described in Generating the absolute URL, before copying the value to the element instances. The shadow tree itself uses the same document base URL as the document that includes it.

The user agent must ensure that all mutations to the referenced document subtree are reflected in the shadow tree. This includes changes to elements, attributes, and text and other nodes. In addition, changes to the stylesheets in effect for the referenced graphics must be reflected in changes to the stylesheets in the shadow tree's scope, as described futher in the section on style inheritance.

If either the use element or the referenced element is altered in a way that causes the use element's URL reference to become unresolved again, then the entire shadow tree for that use element is discarded.

When a use references another element which is another use or whose content contains a use element, then the shadow DOM 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 invalid circular reference. The use element or element instance whose shadow tree would create the circular reference is in error and must not be rendered by the user agent.

5.5.2. Layout of re-used graphics

The value of the x, y, width and height properties on a use element are used to position the re-used graphics and to set the viewport size if the referenced element defines a nested viewport. The effect of these properties on a use element is notably different from their effect on a graphics element, or from their effect in CSS box layout.

The x and y properties define an additional transformation (translate(x,y), where x and y represent the computed value of the corresponding property) to be applied to the use element, after any transformations specified with other properties (i.e., appended to the right-side of the transformation list).

For historical reasons, the supplemental transformation is applied to the use element itself, rather than solely to the re-used content in the shadow tree. This affects the coordinate system used for any masks, clipping paths, or filters applied to the use element and calculated in userSpaceOnUse units.

To apply userSpaceOnUse graphical effects in an un-transformed coordinate space, while also using the x and y to position the graphics, authors can nest the use element inside a g, and apply the graphical effects to the g element.

The width and height properties on the use element override the values for the corresponding properties on a referenced svg or symbol element when determining the used value for that property on the instance root element. However, if the computed value for the property on the use element is auto, then the property is computed as normal for the element instance.

These properties can therefore be used to scale a graphic that defines its own coordinate system, each time it is re-used. Because auto is the initial value, if dimensions are not explicitly set on the use element, the values set on the svg or symbol will be used as defaults.

The width and height properties on the use element have no effect if the referenced element does not establish a new viewport. In particular, the use element does not itself establish a new viewport, and therefore does not affect the interpretation of percentages in the re-used graphics.

In all other ways, rendering and layout of elements within the use-element shadow tree occurs as if the use element was a container for its shadow content. In particular, unless elements within the shadow tree establish a new viewport, they must be drawn in the coordinate system in which the use element is defined (including any cumulative transformations). This affects the interpretation of percentage lengths, and also graphical effects with userSpaceOnUse units.

5.5.3. Style Scoping and Inheritance

The use-element shadow tree, like other shadow trees, exhibits style encapsulation, as defined in the CSS Scoping module [css-scoping-1]. This means that elements in the shadow tree inherit styles from its host use element, but that style rules defined in the outer document do not match the elements in the shadow tree. Instead, the shadow tree maintains its own list of stylesheets, whose CSS rules are matched against elements in the shadow tree.

Presentation attributes and the style attribute are cloned from the elements in the referenced graphics into the element instances in the same manner as other attributes.

When the referenced element is from the same document as the use element, the same document stylesheets will apply in both the original document and the shadow tree document fragment. Any changes to the stylesheets in the main document also affect the shadow tree; the StyleSheetList object accessed through the document and shadow root document fragment's styleSheets properties must be identical. If a style element is duplicated as part of the referenced document subtree, then the styleSheet property on the element instance points to the same object as for the corresponding element.

When the referenced element is from an external document, the stylesheet objects generated when processing that document apply to the shadow tree, and are read-only. All URL references in the stylesheet, including fragment-only references, must be made absolute, relative to the URL of the document that contains the referenced element. User agents may re-use the same stylesheet objects for any shadow trees that reference that same external document.

Style rules that are scoped to the shadow tree cannot normally affect any elements in the main document. Similarly, style rules in the main document can only affect the shadow tree elements by changing inherited values. However, CSS Scoping defines special selectors for styling the host element from within the shadow tree, or for adjusting styles within the shadow tree in response to changes in the host's context [css-scoping-1].

CSS media queries within a shadow tree's scope are evaluated using the same device features and dimensions as the corresponding "light" document (that is, the document that contains the corresponding use element for the shadow tree, after recursively exiting all nested shadow trees).

In most cases, the element instance in the shadow tree will match the same style rules as its corresponding element in the original document. However, if a CSS rule uses a complex selector to match an element based on its ancestors or siblings, and those ancestors or siblings are not cloned as part of the shadow tree, then that rule would no longer match the element instance. Similarly, child-indexed pseudo-classes such as nth-of-type and nth-child may apply to one element but not the other. This represents a change from how style cloning was defined in previous versions of SVG.

The following example demonstrates both the consistent and changed style-matching rules. The circle on the left is re-used to draw the circle on the right. The original circle has styles set in various ways:

In the SVG 1.1 style-cloning model, the specified style values would be cloned from the original element to the element instance. The re-used circle would have the same styles as the original, except that the fill value would be inherited from the use (orange) instead of from the g (blue).

In the shadow DOM model required by SVG 2, the styles for the re-used circle are calculated as follows:

The re-used circle therefore differs from the original in both fill color (because it inherits from a different element) and stroke color (because the complex selector no longer matches).

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="200" height="100" viewBox="0 0 200 100">
  <title>Style inheritance and the use element</title>
  <desc>
    Two circles, one of which is a re-styled clone of the other.
    This file demonstrates one of the cases where 
    the shadow-DOM style matching rules in SVG 2
    have a different effect than the SVG 1.1 style cloning rules. 
    The original circle on the left
    should have blue fill 
    and green stroke.
    In a conforming SVG 1.1 user agent,
    the re-used circle on the right
    should have orange fill and green stroke.
    In a conforming SVG 2 user agent,
    the re-used circle should have orange fill and purple stroke.
    In all cases,
    the stroke should be partially transparent
    and 20 units wide, 
    relative to a total circle diameter of 100 units.
  </desc>
  <style type="text/css">
    circle          { stroke-opacity: 0.7; }
    .special circle { stroke: green; }
    use             { stroke: purple;
                      fill: orange; }
  </style>
  <g class="special" style="fill: blue">
     <circle id="c" cy="50" cx="50" r="40" 
             stroke-width="20" />
  </g>
  <use xlink:href="#c" x="100" />
</svg>
Example Use-changed-styles — A 'use' element copying a 'circle', with various style matching rules demonstrated

Example Use-changed-styles

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

Previous versions of SVG were not clear about how dynamic pseudo-classes (such as :hover) should apply to element instances. The shadow tree model requires that all such pseudo-classes are matched independently to the element instance or to its corresponding element, depending on which element the user is interacting with.

Specifying 'visibility:hidden' on a use element does not guarantee that the referenced content will not be rendered. Unlike the display or the opacity properties, the visibility property does not appy directly to container elements, and therefore does not apply directly to the use element. Because visibility is normally inherited, hiding the use element will often hide the child content, but not necessarily. If any graphics elements in the shadow tree have 'visibility:visible' specified, then that element will be visible even if the use element specifies 'visibility:hidden'.

In the following example, key style rules are as follows:

.dark {
  visibility: hidden;
}
.eyes {
  visibility: visible;
}
svg:hover .dark, svg:focus .dark {
  visibility: visible;
}

The "dark" class is set on the group containing the use elements, so all parts of the re-used graphics inherit the hidden visibility setting, except for the subtrees with class "eyes", where it is reset to visible. Upon hovering or focusing the graphic, the hiding effect is removed.

Multiple use-copies of a creature-symbol on a black background; the use elements have visibility: hidden, but the creatures' eyes have visibility: visible.

Example Use-visibility-hidden, default styles

Multiple use-copies of a rabbit-symbol on a light green background; each rabbit has different=coloured fur, but the same pink noses and white fluffy tails.

Example Use-visibility-hidden, interactive styles

View this example as SVG

The example also demonstrates inheritance of other style properties (fill and stroke) specified on the use elements, and how these are also not used if any elements within the symbol specify explicit values (e.g., the pink noses and ears and the white tails).

5.5.4. Animations in use-element shadow trees

The Web Animations API [web-animations-1] and the SVG Animations specification [svg-animation] define non-CSS ways to animate attributes and styles on targetted elements without directly manipulating DOM properties (see the Animation appendix for details). User agents that implement those features must ensure that all animations that apply to an element in a referenced document subtree also apply to instances of that element in a use-element shadow tree, as described in this section.

Scripted animations created by directly manipulating attributes on elements in the referenced graphics (including the style attribute or its IDL property) will be propagated to the element instances in the shadow tree in the same manner as any other DOM manipulations.

Animation effects applied using CSS will be duplicated along with other stylesheet rules, following the procedure specified in the Style Scoping and Inheritance section.

All animations within a use-element shadow tree operate in the same document timeline as for the corresponding use element, regardless of whether the referenced element is from the same or an external document.

For animation effects applied using a Web Animations API method [web-animations-1], if the target of the animation is a corresponding element to an element instance in a shadow tree, the user agent must construct a ShadowAnimation whose source is that Animation object and whose target is the element instance. If there are multiple instances of the element in different trees, then there will be multiple shadow animations, one for each.

The user agent must create such a ShadowAnimation for all Web Animations API animations in effect (including pending and frozen animations) at the time the shadow tree is generated, and for any new animations applied while the shadow tree exists. The user agent must not create ShadowAnimation objects for CSS animations or animation elements (as these are duplicated separately).

As part of the interface definition, a ShadowAnimation is read-only, and must reflect any changes to its sourceAnimation.

Any attempts to directly apply new animations to a target that is a read-only element instance (or pseudo-element) within a use-element shadow tree must throw a NoModificationAllowedError.

For each animation element [svg-animation] that targets an element in the referenced document subtree, the user agent must ensure that an equivalent animation element is in effect in the use-element shadow tree. If the animation element itself is part of the referenced document subtree, then this happens as a matter of course through the creation of an element instance for the animation element. Otherwise, the user agent must generate an element instance for the animation element that has the same effect as if it was a node in the shadow tree. The effective document order for these generated animation elements must be the same as the document order for their corresponding elements.

Each animation element or instance must only affect a target element in the same node tree (shadow or light), regardless of whether the targetting is implicit (the parent element) or explicit (a URL cross-reference to an element id). In this way, the one-to-one relationship between animation elements and target elements is preserved.

The id attribute is cloned, like any other attribute, from the corresponding element to the element instance; This does not conflict with the requirement for id to be unique, because the clone and the original are in distinct node trees.

All animation elements, in the document or in the shadow trees, which are timed to begin or end in response to an event on another element identified by its id attribute, must also begin or end when any instance of an element with that id receives the same event. This is consistent with how event listeners on a referenced element also listen to events on instances of that element, as described in the section on Event handling in use-element shadow trees. This behavior does not apply to animation begin or end times defined only by an event and not by an id (and therefore implicitly listening for the event on the target element); in that case, each animation element is only triggered by its own target.

At the time an instance of an animation element is generated within a shadow tree, if there is an active animation associated with the corresponding element (including a frozen animation), and the timing event that initiated that animation would also have initiated the instance if it existed, then the animation for the element instance must be initiated, with its begin time adjusted backwards in the document timeline to match the timing of the corresponding element.

In many cases, the requirements of this section mean that the element instance and its corresponding element will animate synchronously. This will be the case if the animation is purely time-based, or if it begins and ends in response to user interaction on an element referenced by its id. However, if the animation is triggered by a user interaction event on the targetted element (implicitly), then only the element or element instance that receives the interaction event will display the animation.

This is a change from previous versions of SVG, which required all animations on the corresponding element to be mirrored, regardless of user interaction, but which did not offer clear guidance for responding to user interactions with the element instances. The change ensures that interactive animations declared with animation elements behave in the same manner as interactive CSS styles and CSS animations.

In order to create animations that apply to all instances when any instance or the original element receives an event, specify the element id explicitly:


<set href="#target" begin="mouseover" ... />
  <!-- only affects the element that is moused over -->

<set href="#target" begin="target.mouseover" ... />
  <!-- affects all instances of the element with the id 'target',
          in all light and shadow node trees,
          when any of them are moused over -->
  

5.5.5. Event handling in use-element shadow trees

Element in a use-element shadow tree can both listen for and be the target of DOM events. Event retargetting provides encapsulation, so that the details of the shadow DOM structure are masked when an event bubbles out of the shadow tree and into the light.

Event retargeting is new in SVG 2. It provides consistency with the Shadow DOM specification, with existing implementations, and with the expectations of authors who are only concerned with elements in the main DOM.

Any event listeners defined on an element in the referenced graphics must also listen for the same event, at the same capture phase, on each instance of that element in a use-element shadow tree. This includes event listeners assigned using event attributes (which would be duplicated as with any other DOM attribute) and also event listeners assigned using the addEventListener method. The user agent must ensure that the list of event listeners for each element instance is synchronized to match its corresponding element. An event listener cannot be directly assigned to a read-only element instance in a use-element shadow tree. Any attempt to add an event listener to such an element must throw a NoModificationAllowedError.

Events in the use-element shadow tree are dispatched and bubble according to the shadow tree event path and event retargeting algorithm [DOM].

In general, the event path for a use-element shadow tree is constructed from the ancestors of the event target element up to the shadow root, then the host use element and its event path through to the document window. This means that, in the capture phase, an event propagates from the window through the regular document tree to the use element and then to the shadow root object and down through the shadow tree (or recursively through multiple shadow trees) to the event target element. In the bubbling phase, the event passes in the opposite direction, from the shadow tree elements to the shadow root, then to the use element and its ancestors.

The event retargeting algorithm ensures that from the perspective of event listeners on the use element or its ancestors, all events targetted to element instances in the shadow tree instead have a target of the use element itself. If the event has both a target and a relatedTarget, and both of these properties would be retargeted to point to the same use element, then the event is not propagated at all outside of the shadow tree. This would occur, for example, if focus moved from one element inside the shadow tree to another. Certain other event types are constrained to not propagate outside of the shadow tree in which they were created.

In contrast, event listeners that process the event while it is propagating through the shadow tree (because the listener has been added to a corresponding element) will receive the event with its target pointing to a read-only element instance in the shadow tree. The correspondingElement and correspondingUseElement properties of that element instance can be used to connect it to the modifiable elements in the main DOM.

5.6. Conditional processing

5.6.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.

When an element is excluded because of conditional processing, it is treated as if it had a used value of none for the display property. 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:

Previous versions of SVG included a third conditional processing attribute, requiredFeatures. This was intended to allow authors to provide fallback behavior for user agents that only implemented parts of the SVG specification. Unfortunately, poor specification and implementation of this attribute made it unreliable as a test of feature support.

5.6.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 2 are requiredExtensions and systemLanguage.

5.6.3. The ‘switch’ element

switch
Categories:
Container element, renderable element
Content model:
Any number of the following elements, in any order:a, foreignObject, g, image, 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.

In SVG, when evaluating the systemLanguage attribute, the order of evaluation of descendant elements of the switch element must be as if the 'allowReorder' attribute, defined in the SMIL specification [SMIL] always has a value of 'yes'.

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.

5.6.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.

5.6.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 language tags indicated by user preferences is a case-insensitive match of one of the language tags given in the value of this parameter, or if one of the language tags indicated by user preferences is a case-insensitive prefix of one of the language tags 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.

5.7. The ‘desc’ and ‘title’ elements

5.7.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.

Multilingual descriptive text selection, based on the lang attribute, was 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. The display value for the title and desc elements must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

Multiple sibling desc or title elements must have different languages, as defined using a lang attribute (or xml:lang attribute) on the descriptive element or an ancestor. The user agent must select the element of each type whose language best matches language preferences set by the user. A descriptive element with an empty-string language tag (indicating no language, for example a text alternative consisting of emoji symbols) is a lowest-priority match for any user, ranked below all user-specified language preferences. If multiple equally valid matches exist, the first match should be used. If no match exists for either 'title' or 'desc', the first element of that type must be selected.

The following example shows alternative language titles on a re-used star icon, inline in an HTML document. The example assumes that the HTML document as a whole has a correctly-declared language of en (English without a specified country code).

<svg>
  <use href="#star">
    <title>Favourite</title>
    <title lang="en-us">Favorite</title>
    <title lang="nl">Favoriet</title>
    <title lang="">★</title>
  </use>
</svg>
  

The first title element inherits the language of the document (en); the others have explicitly-declared languages for each element. If the user's preferred language (out of those provided) is American English, the icon title is the American spelling "Favorite". If the user's preferred language is Dutch, the icon title is "Favoriet". If the user's preference list includes generic English ranked higher than Dutch, the title is "Favourite" with British spelling. If the user does not understand either Dutch or English, the title will be the star symbol character—which is not ideal (most screen readers will read it as a localized version of "black star"), but better than no text alternative at all.

Authors should be aware that SVG 1.1-supporting user agents that have not yet implemented multi-lingual descriptive text will normally select the first element of each type, regardless of user preferences. SVG 1.1 user agents may also fail to recognize a title element that is not the first child of its parent, or a desc element that has previous siblings that are not other descriptive elements.

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

User agents must make the text content of selected 'title' and 'desc' elements available to platform accessibility APIs as part of the name and description computation for the parent element, as defined in the SVG Accessibility API Mappings [SVG-AAM] specification.

Inclusion of any 'title' or 'desc' elements as a direct child of a rendered element indicates that the rendered element is of semantic importance in the graphic. Authors should not, and SVG generators must not, include empty 'title' or 'desc' elements with no text content or whitespace-only text content, as this will result in a nameless object being presented to assistive technology users.

If an individual graphic element has no meaning on its own, alternative text should instead be provided for the nearest container element that describes a meaningful object. Authors should use grouping (g) elements to structure their drawing elements into meaningful objects, and name those groups with title. Conversely, if a container object is used simply to apply styles or layout, and neither defines an object nor provides meaningful grouping structure, it does not need alternative text.

Descriptive text elements whose parent is not rendered may be used by authors or authoring tools as reference information; authors are warned that this data is not normally available to end users viewing the graphic through assistive technologies. Nonetheless, a non-rendered element may be referenced as part of the accessible name or description of a rendered element (as defined in SVG-AAM), and the recursive computation will use descriptive child elements of the referenced element.

Description and title elements may contain marked-up text from other namespaces, using standard XML mechanisms to indicate the namespace. However, authors should not rely on such markup to provide meaning to alternative text; only the plain text content is currently required to be exposed to assistive technologies.

The HTML parser treats all markup within title and desc the same way it treats markkup in an HTML fragment; most elements will be assigned to the HTML namespace.

User agents may use markup within title to influence the visual presentation of titles (such as tooltips), but are not required to do so.

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

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 a short description of the graphic; on interactive content, it could be a label for, or instructions for, use of the element; and so forth.

Authors should not provide redundant information in a title element if there is also a visible label for the drawing element (e.g., using a text element). Instead, the visual label should be associated with the drawing element using an aria-labelledby attribute.

Interactive user agents should make the plain text content of title elements available in response to user interaction, in a manner consistent with platform conventions; existing user agents commonly render title elements as a tooltip on hovering the parent element.

Authors should provide a title child element to the root 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 root svg element available to users. However, this is typically done through other means than the tooltips used for nested SVG and graphics elements, e.g., by displaying in a browser tab.

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

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 a description of the visual appearance of a graphic or help to explain the functionality of a complex widget. It is not typically available to other users, so should not be used for essential instructions.

Authors may associate detailed information, including visible text, with part of the graphic using aria-describedby attribute (on the described element or a parent container), with the value being an ID reference to one or more SVG or HTML elements containing the description. The aria-describedby attribute takes precedence over the child desc when providing a description. If an element has both visible description and a child desc element providing supplementary information, authors should explicitly include the id of the element itself in its own aria-describedby list, in order to concatenate the two descriptions together.

5.8. 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-names].

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:

Metadata content is not directly rendered; the display value for the metadata element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

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>

5.9. 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 or use element references. However, when processing URL references to identify a specific target element, the user agent must always compare the generated absolute URL against the current document base URL to determine whether it is a same-document URL reference. In this way, target-fragment only references to elements in the same document remain valid, regardless of any changes to the document base URL.

5.10. Foreign namespaces and private data

SVG allows inclusion of elements from foreign namespaces anywhere within the SVG content. In general, the SVG user agent must include the unknown foreign-namespaced elements in the DOM but will ignore and exclude them for rendering purposes.

The notable exceptions is described in the Embedded Content chapter under Embedding Foreign Object Types.

Additionally, SVG allows inclusion of attributes from foreign namespaces on any SVG element. The SVG user agent must include unknown attributes in the DOM but should otherwise ignore unknown attributes.

Authors should be aware that unknown namespaced elements and attributes will not be parsed as such by the HTML parser. Instead, the namespace prefix will be included in the tag or attribute name, elements will be placed in the parent element namespace and attributes in the default namespace.

To add custom attributes in a way that will result in consistent parsing in both XML and HTML documents, authors may use the ‘data-*’ attributes. These can be added to SVG metadata elements if the information they encode is not associated with any other element in the document.

SVG's ability to include foreign namespaces can be used for the following purposes:

For example, a business graphics authoring application might want to include some private data within an SVG document so that it could properly reassemble the chart (a pie chart in this case) upon reading it back in:

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
     xmlns = 'http://www.w3.org/2000/svg'>
  <defs>
    <myapp:piechart xmlns:myapp="http://example.org/myapp"
                    title="Sales by Region">
      <myapp:pieslice label="Northern Region" value="1.23"/>
      <myapp:pieslice label="Eastern Region" value="2.53"/>
      <myapp:pieslice label="Southern Region" value="3.89"/>
      <myapp:pieslice label="Western Region" value="2.04"/>
      <!-- Other private data goes here -->
    </myapp:piechart>
  </defs>
  <desc>This chart includes private data in another namespace
  </desc>
  <!-- In here would be the actual SVG graphics elements which
       draw the pie chart -->
</svg>

5.11. Common attributes

5.11.1. Definitions

core attributes
The core attributes are those attributes that can be specified on any SVG element. The core attributes are id, tabindex, autofocus, lang, xml:space, class and style, along with all custom data attributes.

5.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 [DOM]. The id attribute must be unique within the node tree, must not be an empty string, and must not contain any whitespace characters.

Additional requirements apply in order for the id attribute to be valid in XML documents, as defined in the specification for the relevant version of XML. A stand-alone SVG document uses XML 1.0 syntax [xml], which specifies that valid id values are XML name tokens. Valid XML 1.0 names only include designated characters (letters, digits, and a few punctuation marks), and do not start with a digit, a full stop (.) character, or a hyphen-minus (-) character.

User agents should process id values in SVG files irrespective of XML validity.

Authors should avoid the use of id values that would be parsed as an SVG view specification or a basic media fragment when used as a URL target fragment.

5.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 [xml].

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].

5.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 [xml] and to the discussion white space handling in SVG.

New content should use the white-space property instead.

5.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.

5.11.6. The ‘autofocus’ attribute

Name Value Initial value Animatable
autofocus boolean attribute [HTML] (none) no

This content attribute allows authors to ask a focusable element to be focused after it's connected to a document. See autofocus in the HTML specification for details.

The attribute has no effect if the element is not already focusable.

5.11.7. 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.

5.12. WAI-ARIA attributes

5.12.1. Definitions

ARIA attributes
These are the attributes defined in WAI-ARIA, consisting of WAI-ARIA states and properties as well as the role attribute. 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-keyshortcuts, aria-label, aria-labelledby, aria-atomic, aria-live, 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-level.

Note that the above list of ARIA attributes may be expanded by future WAI-ARIA specifications.

5.12.2. Role attribute

Any renderable element may have an ARIA role attribute specified; the role attribute is ignored on non-rendered elements. 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 ([wai-aria], section 5.4) and Graphics Roles ([graphics-aria-1.0], section 4).

The WAI-ARIA role that an SVG element has assigned to it is the first valid role found in the list of tokens generated when the role attribute is split on spaces. A valid role is a recognized, non-abstract role that is allowed for the element type.

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 ([wai-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.

To be valid and useful, many element roles require additional information to be provided in the form of an accessible name or explicit state and property values. Accessible names may be provided using SVG descriptive elements or ARIA attributes. The requirements for each role are indicated where the role is defined, e.g., in WAI-ARIA ([WAI-ARIA]) or the WAI-ARIA Graphics Module ([graphics-aria-1.0]).

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

WAI-ARIA state and property attributes may be specified on SVG elements. These attributes are defined by ARIA in Definitions of States and Properties (all aria-* attributes) ([wai-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 ([wai-aria], section 10.2).

The attributes are animatable; if animation is used to change the state of the graphic, or to change its content in a way that alters the correct alternative text description, the same method of animation should be used to update the corresponding ARIA state or property attribute.

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. [wai-aria] [svg-aam-1.0]

5.12.4. Implicit and Allowed 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.

For many graphics elements, an implicit role is only assigned if the author provides information that indicates semantic importance. The complete inclusion criteria for the accessibility tree are defined by the SVG Accessibility API Mappings specification for user agents [svg-aam-1.0]. For authors, the preferred means of indicating semantic importance is to provide an accessible name for the element. This can be done through a direct child title element, or through the aria-label or aria-labelledby attributes. Authors should use one of these methods to provide an accessible name for any content that is essential to the comprehension of the SVG, and especially for any interactive content.

Language feature Default implied ARIA semantics Allowed roles
a link role if the element has a valid href or xlink:href attribute. For a elements that are not links, the default semantics are the same as tspan if the a element is a descendent of text, or the same as g otherwise. no restrictions
circle graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
clipPath none no role may be applied
defs none no role may be applied
desc none no role may be applied
ellipse graphics-symbol role if the element meets the inclusion criteria, otherwise none 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 group role if the element meets the inclusion criteria, otherwise none no restrictions
g group role if the element meets the inclusion criteria, otherwise none no restrictions
image img role no restrictions
line graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
linearGradient none no role may be applied
marker none no role may be applied
mask none no role may be applied
metadata none no role may be applied
mpath none no role may be applied
path graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
pattern none no role may be applied
polygon graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
polyline graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
radialGradient none no role may be applied
rect graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
script none no role may be applied
stop none no role may be applied
style none no role may be applied
svg graphics-document role no restrictions
switch none no role may be applied
symbol graphics-object role if the element is a rendered element instance that meets the inclusion criteria, otherwise none no restrictions
text grouprole, with platform-specific role mappings, as defined in the SVG Accessibility API Mappings specification no restrictions
textPath group role if the element meets the inclusion criteria, otherwise none no restrictions
title none no role may be applied
tspan group role if the element meets the inclusion criteria, otherwise none no restrictions
use graphics-object role if the element meets the inclusion criteria, otherwise none no restrictions
view none no role may be applied

5.13. DOM interfaces

5.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.

5.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.

[Exposed=Window]
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);

  undefined deselectAll();

  SVGNumber createSVGNumber();
  SVGLength createSVGLength();
  SVGAngle createSVGAngle();
  DOMPoint createSVGPoint();
  DOMMatrix createSVGMatrix();
  DOMRect createSVGRect();
  SVGTransform createSVGTransform();
  SVGTransform createSVGTransformFromMatrix(optional DOMMatrix2DInit matrix = {});

  Element getElementById(DOMString elementId);

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

SVGSVGElement includes SVGFitToViewBox;
SVGSVGElement includes 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 an additional transform applied to the SVG. They only have an effect on the outermost svg element of an SVG document fragment.

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.

Previous versions of SVG recommended that user agents implement controls, by default, for the user to set the scale (zoom) and translate (pan) of the graphic. Transformations from these user actions would be reflected in the values of currentScale and currentTranslate. These user controls were not well implemented, and are no longer recommended. However, authors should be aware that the user agent may update these values.

The obsolete attribute zoomAndPan="disable", on the outermost SVG element, should disable any user agent manipulation of the values based on user action, but may have unwanted side effects in some user agents.

The interaction of currentScale and currentTranslate with other ways of transforming the document root (transforms and SVG views) is poorly defined. See the GitHub issue for more.

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.

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 root 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 elements in the use-element shadow tree, we don't place the element instances or their corresponding element 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. ([DOM], 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. [DOM][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.

The getElementById method, must return the first element in tree order, within the svg element's descendants, whose ID is elementId, or null if there is no such element.

5.13.3. Interface SVGGElement

An SVGGElement object represents a g element in the DOM.

[Exposed=Window]
interface SVGGElement : SVGGraphicsElement {
};

5.13.4. Interface SVGDefsElement

An SVGDefsElement object represents a defs element in the DOM.

[Exposed=Window]
interface SVGDefsElement : SVGGraphicsElement {
};

5.13.5. Interface SVGDescElement

An SVGDescElement object represents a desc element in the DOM.

[Exposed=Window]
interface SVGDescElement : SVGElement {
};

5.13.6. Interface SVGMetadataElement

An SVGMetadataElement object represents a metadata element in the DOM.

[Exposed=Window]
interface SVGMetadataElement : SVGElement {
};

5.13.7. Interface SVGTitleElement

An SVGTitleElement object represents a title element in the DOM.

[Exposed=Window]
interface SVGTitleElement : SVGElement {
};

5.13.8. Interface SVGSymbolElement

An SVGSymbolElement object represents a symbol element in the DOM.

[Exposed=Window]
interface SVGSymbolElement : SVGGraphicsElement {
};

SVGSymbolElement includes SVGFitToViewBox;

New in SVG 2. The SVGSymbolElement interface now inherits from SVGGraphicsElement, so that the instantiated symbol in the shadow DOM can be queried as a graphics element.

5.13.9. Interface SVGUseElement

An SVGUseElement object represents a use element in the DOM.

[Exposed=Window]
interface SVGUseElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGElement? instanceRoot;
  [SameObject] readonly attribute SVGElement? animatedInstanceRoot;
};

SVGUseElement includes 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.

The instanceRoot and animatedInstanceRoot IDL attributes both point to the instance root, the SVGElementInstance that is a direct child of this element's shadow root (u.instanceRoot is equivalent to getting u.shadowRoot.firstChild). If this element does not have a shadow tree (for example, because its URI is invalid or because it has been disabled by conditional processing), then getting these attributes returns null.

5.13.10. Interface SVGUseElementShadowRoot

The root object of each use-element shadow tree implements the SVGUseElementShadowRoot interface. This interface does not currently define any extensions to the properties and methods defined for the ShadowRoot interface and DocumentOrShadowRoot mixin. However, the tree rooted at this node is entirely read-only from the perspective of author scripts.

[Exposed=Window]
interface SVGUseElementShadowRoot : ShadowRoot {
};

5.13.11. Mixin SVGElementInstance

The SVGElementInstance interface defines extensions to the SVGElement interface, which are only used for elements in a use-element shadow tree.

In previous versions of SVG, SVG element instances were defined as non-element objects that were valid event targets but not full DOM nodes. This specification re-defines the use-element shadow tree to be consistent with the Shadow DOM specification, which means that instances are actual SVGElement objects. This interface adds the missing functionality for backwards compatibility. However, authors should be aware that compatibility is not perfect, and design their scripts accordingly. Also note that these properties will not be available on HTML-namespaced element objects in the shadow tree.

interface mixin SVGElementInstance {
  [SameObject] readonly attribute SVGElement? correspondingElement;
  [SameObject] readonly attribute SVGUseElement? correspondingUseElement;
};

The correspondingElement IDL attribute points to the corresponding element if this element is an element instance in a use-element shadow tree, or is null otherwise.

When the referenced element is in an external file, the presence of this pointer implies that the entire DOM of the external file must be maintained in memory. However, as currently specified, the external DOM is read-only. It therefore offers limited functionality and a potentially large performance impact. Pending feedback from implementers, authors should consider the use of correspondingElement with external file references to be at-risk.

The correspondingUseElement IDL attribute points to the corresponding use element if this element is an element instance in a use-element shadow tree, or is null otherwise.

5.13.12. Interface ShadowAnimation

The ShadowAnimation inteface defines a read-only Animation object, which mirrors all changes to the sourceAnimation object from which it was constructed. They are used to mirror author-initiated animation objects in the use-element shadow tree.

[Exposed=Window]
interface ShadowAnimation : Animation {
  constructor(Animation source, (Element or CSSPseudoElement) newTarget);
  [SameObject] readonly attribute Animation sourceAnimation;
};

The sourceAnimation IDL property points to the Animation object passed in the constructor.

The constructor generates a new ShadowAnimation object, which reflects all properties on the sourceAnimation, except that its effect is created by constructing a new KeyframeEffectReadOnly using the keyframe effect of the sourceAnimation as its source, and then modifying its target to match the newTarget parameter.

A ShadowAnimation is read-only. Any attempt to set any of the inherited IDL properties, or call any of the Animation methods that change its state, must throw a NoModificationAllowedError. However, the user agent must ensure that any changes to the properties or state of the sourceAnimation are reflected in changes to the ShadowAnimation.

5.13.13. Interface SVGSwitchElement

An SVGSwitchElement object represents a switch element in the DOM.

[Exposed=Window]
interface SVGSwitchElement : SVGGraphicsElement {
};

5.13.14. Mixin 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.

interface mixin 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.