4.1. Defining an SVG document fragment: the ‘svg’ element
4.1.1. Overview
The content model and set of allowed attributes, as listed
in definitions.xml, needs to be reviewed for consistency across all elements.
An SVG document fragment consists of any number of SVG elements
contained within an ‘svg’ element.
An SVG document fragment can range from an empty fragment (i.e.,
no content inside of the ‘svg’ element), to a very simple SVG
document fragment containing a single SVG graphics element
such as a ‘rect’, to a complex, deeply nested collection of
container elements and graphics elements.
An SVG document fragment can stand by itself as a self-contained
file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent
HTML or XML document.
The following example shows simple SVG
content embedded inline as a fragment within a parent XML document.
Note the use of XML namespaces to indicate that the ‘svg’ and
‘ellipse’ elements belong to the SVG namespace:
‘svg’ elements can appear in the middle of SVG content. This
is the mechanism by which SVG document fragments can be embedded within
other SVG document fragments.
Another use for ‘svg’ elements within the middle
of SVG content is to establish a new SVG viewport. (See
Establishing a new
SVG viewport.)
4.1.2. Namespace
When SVG is parsed as a XML, for compliance with the
Namespaces in XML Recommendation
[XML-NS], an SVG namespace
declaration must be provided so that all SVG elements are identified
as belonging to the SVG namespace.
When using the HTML syntax, the namespace is provided automatically by the HTML parser.
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:
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:
Namespace prefixes can be specified on ancestor elements (illustrated
in the above example). For more
information, refer to the Namespaces in XML Recommendation
[XML-NS].
4.1.3. Definitions
structural element
The structural elements are those which define the primary
structure of an SVG document. Specifically, the following
elements are structural elements:
‘defs’, ‘g’, ‘svg’, ‘symbol’ and ‘use’.
structurally external element
Elements that define its structure by reference to an external resource.
Specifically, the following elements are structurally external elements when
they have an ‘href’ attribute:
‘audio’, ‘foreignObject’, ‘iframe’, ‘image’, ‘script’, ‘use’ and ‘video’.
SVG user agent
An SVG user agent is a user agent that is able to retrieve and
render SVG content.
user agent
The general definition of a user agent is an application
that retrieves and renders Web content, including text,
graphics, sounds, video, images, and other content types. A
user agent may require additional user agents that handle
some types of content. For instance, a browser may run a
separate program or plug-in to render sound or video. User
agents include graphical desktop browsers, multimedia
players, text browsers, voice browsers, and assistive
technologies such as screen readers, screen magnifiers,
speech synthesizers, onscreen keyboards, and voice input
software.
A "user agent" may or may not have the ability to retrieve
and render SVG content; however, an "SVG user agent"
retrieves and renders SVG content.
current SVG document fragment
The document sub-tree which starts with the outermost
ancestor ‘svg’ element of a given SVG
element, with the requirement that all container elements
between the outermost ‘svg’ and the given element are
all elements in the SVG namespace.
A document sub-tree which starts with an ‘svg’
element which is either the root element of the document or whose parent
element is not in the SVG namespace.
An SVG document fragment can consist of a stand-alone SVG document,
or a fragment of a parent document enclosed by an ‘svg’
element.
When an ‘svg’ element is a descendant of another ‘svg’
element, only the outermost svg element is the root of an SVG
document fragment.
A graphics element which uses a reference to a different
document or element as the source of its graphical content.
Specifically: ‘audio’, ‘iframe’, ‘image’, ‘mesh’, ‘use’ and ‘video’.
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%.
Attribute definitions:
Name
Value
Initial value
Animatable
zoomAndPan
disable | magnify
magnify
no
Specifies whether the user agent should supply a means to zoom
and pan the SVG content. See the definition of ‘zoomAndPan’
for details.
If an SVG document is likely to be referenced as a component
of another document, the author will often want to include a
‘viewBox’ attribute on the outermost svg element of the
referenced document. This attribute provides a convenient way to design
SVG documents to scale-to-fit into an arbitrary SVG viewport.
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>
Treating unknown elements as a generic container element, resulting in the
rendering of their child trees, and assigning the SVGUnknownElement interface to
unknown elements are both at risk, with no known implementations.
Unknown elements are all elements that are in the SVG namespace that are not
defined by this specification or any SVG module. The SVGUnknownElement
interface must be used for unknown elements.
Unknown elements in the SVG namespace are renderable elements and container elements.
They must render as if the unknown element
were replaced with a ‘g’ element or ‘tspan’, according to context.
Any global attribute or property that is valid on any SVG graphics element
is also valid on unknown elements, and must be processed as normal.
This includes conditional processing attributes, ARIA attributes, data attributes,
and the ‘lang’, ‘id’, ‘class’, ‘tabindex’ and ‘style’.
Styles specified on unknown elements must be inherited by
their child elements according to the normal rules for inheritance for each style property.
Known and unknown elements in other namespaces that occur as a child of any
SVG element except ‘foreignObject’, must not render unless
explicitly stated otherwise in this specification.
Known elements in the SVG namespace that occur in places where SVG's content
model doesn't explicitly allow it must not render unless
explicitly stated otherwise in this specification.
Consequently, in the following example:
the ‘path’ element inside the unknown ‘mysteryElement’ must render
‘hideElement’ and its contents must not render
the ‘text’ element must not render the string contained
in the inner ‘text’ element
the ‘path’ element inside of ‘gradientExtension’
must not render since the ‘linearGradient’ element isn't directly rendered
regardless of whether the user agent supports XHTML or not,
the ‘div’ element and its contents must not render
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 200">
<rect x=".1" y=".1" width="699.8" height="199.8"
fill="none" stroke="blue" stroke-width=".2" />
<mysteryElement>
<path d="M0 0h600v200h-600z" fill="darkkhaki"/>
</mysteryElement>
<hideElement xmlns="http://www.example.com/invisibleML">
nothing to see here
<path d="M0 0h300v100h-300z" fill="whitesmoke"/>
</hideElement>
<text y="2em" font-size="20"><text>This text must not be visible</text></text>
<linearGradient>
<gradientExtension>
<path d="M300 0h100v200h-100z" fill="fuchsia"/>
</gradientExtension>
</linearGradient>
<div xmlns="http://www.w3.org/1999/xhtml">This must not be visible</div>
</svg>
4.4. Defining content for reuse, and the ‘defs’ element
4.4.1. Overview
SVG allows graphical objects to be defined for later reuse.
To do this, it makes extensive use of URL references
[RFC3987] to these other objects.
For example, to fill a rectangle with a linear gradient, you first
define a ‘linearGradient’ element and give it an ID, as in:
You then reference the linear gradient as the value of the
fill property for the rectangle, as in:
<rect style="fill:url(#MyGradient)"/>
Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.
It is recommended that, 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.
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.
4.5. The ‘desc’
and ‘title’ elements
4.5.1. Definition
descriptive element
An element which provides supplementary descriptive information about
its parent. Specifically, the following elements are descriptive elements:
‘desc’, ‘metadata’ and ‘title’.
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).
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 authoring tools 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.
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.
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.
Description and title elements may contain marked-up text
from other namespaces.
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.
4.6. The ‘metadata’ element
Metadata which is included with SVG content should be
specified within ‘metadata’
elements. The contents of the ‘metadata’ should be elements from
other XML namespaces, with these elements from these namespaces
expressed in a manner conforming with the Namespaces in XML Recommendation
[XML-NS].
SVG 2 removes the recommendation to structure metadata
elements in any particular way.
Metadata 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.)
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.
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).
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’.
4.7.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.
4.8. The ‘use’ element
SVG 2 Requirement:
Allow ‘use’ to reference an external document's root element by omitting the fragment.
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
must be treated as an illegal value.
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.
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.
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 is a (shadow-including) ancestor
of the ‘use’ element,
then this is an invalid circular reference
and the ‘use’ element is in error.
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.
4.8.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 Shadow DOM specification [SHADOWDOM],
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 any multimedia
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 Shadow DOM specification [SHADOWDOM],
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.
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.
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.
4.8.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.
4.8.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:
stroke-width (20) is set in a presentation attribute on the circle itself.
stroke-opacity (0.7) is set via a CSS rule with a simple selector matching the circle tag name.
stroke color (green) is set using a complex CSS selector, matching the circle as a descendent of an element with class special.
fill color is not set directly on the circle, so is inherited from the style set on the containing ‘g’ element (blue).
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 stroke-width (20) presentation attribute is cloned to the element instance.
the CSS rule setting stroke-opacity (0.7) is part of the CSS stylesheet cloned into the shadow tree; it matches the circle tag name of the element instance, so is applied.
the CSS rule with the complex selector is also part of the cloned stylesheet, but it does not match the element instance of the circle, which is not a descendent of an element with class special; instead, stroke color on the circle is inherited from the host ‘use’ element (purple).
fill color is still not set directly, so is once again inherited from the host ‘use’ element.
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>
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:
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.
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).
The user agent must synchronize playback of the media
with the corresponding element
(if it is rendered as part of the same document)
and any other instances of the same corresponding element
in the document.
The instance must not play any audio
if the ‘use’ element is not rendered.
If user-agent provided playback controls are included
for the corresponding element
(or would be included, if the element was rendered),
then they must be included for all instances in the document,
and a user action on any instance must control playback on them all.
4.8.5. Animations in use-element shadow trees
The Web Animations API
and the SVG Animations specification
define ways to animate attributes and styles
on targetted elements without directly manipulating DOM properties.
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.
For animation effects applied
using a Web Animations API method
[WAAPI],
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 inteface 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 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 -->
4.8.6. 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.
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.
4.9. Conditional processing
4.9.1. Conditional processing overview
SVG contains a ‘switch’ element along with
attributes ‘requiredExtensions’ and ‘systemLanguage’ to provide an
ability to specify alternate viewing depending on the
capabilities of a given user agent or the user's language.
Attributes ‘requiredExtensions’ and ‘systemLanguage’ act as tests and
evaluate to either true or false. The ‘switch’ renders the first of
its children for which all of these attributes test true. If
the given attribute is not specified, then a true value is
assumed.
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’).
conditional processing will
have no effect on never-rendered elements;
in particular, conditional processing does not affect the processing of a ‘style’ or ‘script’ element.
conditional processing of child content of a never-rendered container element
(e.g., a ‘pattern’ or a ‘mask’)
will affect whether that child content contributes to the graphical effect.
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.
4.9.2. Definitions
conditional processing attribute
A conditional processing attribute is one that controls whether
or not the element on which it appears is processed. Most elements,
but not all, may have conditional processing attributes specified
on them. See Conditional processing
for details. The conditional processing attributes defined in
SVG 2 are ‘requiredExtensions’ and ‘systemLanguage’.
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.
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.
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.
Evaluates to "true" if one of the languages indicated by
user preferences exactly equals one of the languages given in
the value of this parameter, or if one of the languages
indicated by user preferences exactly equals a prefix of one of
the languages given in the value of this parameter such that
the first tag character following the prefix is "-".
Evaluates to "false" otherwise.
If the attribute is not present, then it implicitly evaluates to "true".
If a null string or empty string value is
given to attribute ‘systemLanguage’, the attribute evaluates to
"false".
Note: This use of a prefix matching rule does not imply that
language tags are assigned to languages in such a way that it
is always true that if a user understands a language with a
certain tag, then this user will also understand all languages
with tags for which this tag is a prefix.
The prefix rule simply allows the use of prefix tags if this
is the case.
Implementation note: When making the choice of linguistic
preference available to the user, implementers should take into
account the fact that users are not familiar with the details
of language matching as described above, and should provide
appropriate guidance. As an example, users may assume that on
selecting "en-gb", they will be served any kind of English
document if British English is not available. The user
interface for setting user preferences should guide the user to
add "en" to get the best matching behavior.
Multiple languages may be listed for content that is
intended for multiple audiences. For example, content that is
presented simultaneously in the original Maori and English
versions, would call for:
<text systemLanguage="mi, en"><!-- content goes here --></text>
However, just because multiple languages are present within
the object on which the ‘systemLanguage’ test
attribute is placed, this does not mean that it is intended for
multiple linguistic audiences. An example would be a beginner's
language primer, such as "A First Lesson in Latin," which is
clearly intended to be used by an English-literate audience. In
this case, the ‘systemLanguage’ test attribute
should only include "en".
Authoring note: Authors should realize that if several
alternative language objects are enclosed in a ‘switch’, and none of them
matches, this may lead to situations where no content is
displayed. It is thus recommended to include a "catch-all"
choice at the end of such a ‘switch’ which is acceptable in
all cases.
‘systemLanguage’ is often used
in conjunction with the ‘switch’ element. If the ‘systemLanguage’ is used in other
situations, then it represents a simple switch on the given
element whether to render the element or not.
4.10. HTML metadata elements
For user agents that support HTML, the following HTML elements (in
the HTML namespace) must be supported in SVG documents:
The ‘id’ attribute is available on all SVG elements:
Name
Value
Initial value
Animatable
id
(see below)
(none)
no
Must reflect the element's
ID [DOM4]. The ‘id’ attribute
must be any value other than the empty string.
4.11.3. The ‘lang’ and ‘xml:lang’ attributes
The ‘lang’ attribute (in no namespace) specifies the primary language for the element's contents and
for any of the element's attributes that contain text.
The ‘lang’ attribute in the XML namespace is defined in XML [XML10].
If these attributes are omitted from an element, then the language of this element is the same as the language of its parent element, if any.
The ‘lang’ attribute in the XML namespace may be used on SVG elements in XML documents.
If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute
in the XML namespace are specified on the same element, they must have exactly the same value when compared in an ASCII case-insensitive manner.
If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the
XML namespace are set on an element, user agents must use the ‘lang’ attribute in the XML namespace, and
the ‘lang’ attribute in no namespace must be ignored for the purposes of determining the element's language.
The ‘lang’ attribute specifies the primary language for the element's contents and
for any of the element's attributes that contain text. Its value must be a valid BCP 47 language tag,
or the empty string. Setting the attribute to the empty string indicates that the primary language is unknown.
[BCP47].
4.11.4. The ‘xml:space’ attribute
SVG 2 Requirement:
Deprecate the use of ‘xml:space’ to affect text layout and use the ‘white-space’ property instead.
Deprecated XML attribute to specify whether white space
is preserved in character data. The only possible values
are the strings 'default' and 'preserve', without
white space. Refer to the
Extensible Markup Language (XML) 1.0
Recommendation [XML10] and to the
discussion white space
handling in SVG.
New content should use the white-space property instead.
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.
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.
These attributes, if specified, must have a value that is the WAI-ARIA value
type in the "Value" field of the definition for the state or property, mapped to
the appropriate SVG value type according to
Mapping WAI-ARIA Value types to languages
using the SVG mapping ([ARIA], section 10.2).
WAI-ARIA State and Property attributes can be used on any element. They are
not always meaningful, however, and in such cases user agents might not perform
any processing aside from including them in the DOM. State and property attributes are
processed according to the ARIA and
SVG Accessibility API Mappings specification
specifications. [ARIA] [SVG-AAM]
4.12.4. Implicit 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].
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.
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.
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.
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;
};
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.
The
x,
y,
width and
height IDL attributes
reflect the computed values of the x, y, width and
height properties and their corresponding
presentation attributes, respectively.
The currentScale and
currentTranslate IDL
attributes represent the transform applied to the document in
response to user magnification and panning operations, as described under
Magnification and panning.
The document's magnification and panning
transform is a 2x3 matrix of the form
[currentScale 0 0 currentScale currentTranslate.x currentTranslate.y].
The value of the ‘transform’ property does not affect
currentScale or
currentTranslate.
On getting currentScale,
the following steps are run:
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:
Let [abcdef]
be the 2x3 matrix that represents the document's magnification and panning
transform.
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.
Note that the value of the ‘zoomAndPan’ attribute
on the outermost svg element only controls whether the document's
magnification and panning transform can be updated through user interaction.
Regardless of the value of that attribute, the current scale and translation
can be changed by modifying currentScale
and currentTranslate.
The suspendRedraw,
unsuspendRedraw,
unsuspendRedrawAll
and forceRedraw
methods are all deprecated and defined to have no effect. When
the suspendRedraw method is called, it must return 1.
The getIntersectionList,
getEnclosureList,
checkIntersection and
checkEnclosure methods are
used to perform geometry operations on graphics elements to find
those whose (or check whether their) graphical content lies partially or
completely within a given rectangle.
To find the intersecting
or enclosed descendants of a given element element
with a given rectangle rectangle using ancestor
as the element in whose coordinate space rectangle is
to be interpreted, the following steps are run:
Let result be an initially empty list.
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.
For each child element child of element, in document order:
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.
Transform region into ancestor's coordinate system.
If we are finding intersecting descendants and region lies partially
or fully within rectangle, then append child to result.
Otherwise, we are finding enclosed descendants. If region lies
fully within rectangle, then append child to result.
Return result.
To find the non-container
graphics elements within a given element element, the following
steps are run:
Let result be an initially empty list.
If element is an ‘svg’ or ‘g’ element,
then for each child element child of element,
in document order:
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.
If referenceElement is not null, then remove from
descendants any element that does not have referenceElement
as an ancestor.
Return a staticNodeList that contains all of the elements in descendants.
([DOM4], section 5.2.7)
When checkIntersection(element, rect) or
checkEnclosure(element, rect) is called,
the following steps are run:
Let descendants be a list, depending on what method we are in:
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.
If any element in elements is not also in descendants,
then return false.
Return true.
The deselectAll method is
used to remove any selections from the document. When deselectAll() is called,
all ranges
from the document's selection
are removed and the selection's
direction is set to
forwards. [DOM4][EDITING]
This method is deprecated, as it duplicates functionality from the Selection API.
This is equivalent to calling document.getSelection().removeAllRanges()
on the document that this ‘svg’ element is in.
The
createSVGNumber,
createSVGLength,
createSVGAngle,
createSVGPoint,
createSVGMatrix,
createSVGRect and
createSVGTransform
methods are all factory functions used to create a new datatype object
of a particular type. When one of these methods is called, a new
object is returned according to the following table:
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.
4.13.3. Interface SVGGElement
An SVGGElement object represents a ‘g’ element in the DOM.
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.
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.
4.13.11. 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.
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.
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 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.
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.
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.
