Document Structure — SVG 2
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
This example shows a slightly more complex (i.e., it contains
multiple rectangles) stand-alone, self-contained SVG document:
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.
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
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-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
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.
However, 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:
animation elements
animate
animateMotion
animateTransform
set
descriptive elements
desc
title
metadata
paint server elements
linearGradient
radialGradient
pattern
shape elements
circle
ellipse
line
path
polygon
polyline
rect
structural elements
defs
svg
symbol
use
clipPath
filter
foreignObject
image
marker
mask
script
style
switch
text
view
Attributes:
aria attributes
aria-activedescendant
aria-atomic
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-level
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
role
conditional processing attributes
requiredExtensions
systemLanguage
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
document event attributes
onunload
onabort
onerror
onresize
onscroll
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
presentation attributes
viewBox
preserveAspectRatio
transform
Geometry properties:
width
height
DOM Interfaces:
SVGSVGElement
The
and
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:
clipPath
defs
marker
mask
pattern
svg
switch
and
symbol
The
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:
View this example as SVG (SVG-enabled browsers only)
element can contain other
elements nested
within it, to an arbitrary depth.
5.2.2. The
‘g’
element
Categories:
Container element
renderable element
structural element
Content model:
Any number of the following elements, in any order:
animation elements
animate
animateMotion
animateTransform
set
descriptive elements
desc
title
metadata
paint server elements
linearGradient
radialGradient
pattern
shape elements
circle
ellipse
line
path
polygon
polyline
rect
structural elements
defs
svg
symbol
use
clipPath
filter
foreignObject
image
marker
mask
script
style
switch
text
view
Attributes:
aria attributes
aria-activedescendant
aria-atomic
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-level
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
role
conditional processing attributes
requiredExtensions
systemLanguage
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
presentation attributes
DOM Interfaces:
SVGGElement
5.3. Defining content for reuse, and the
‘defs’
element
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:
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:
animation elements
animate
animateMotion
animateTransform
set
descriptive elements
desc
title
metadata
paint server elements
linearGradient
radialGradient
pattern
shape elements
circle
ellipse
line
path
polygon
polyline
rect
structural elements
defs
svg
symbol
use
clipPath
filter
foreignObject
image
marker
mask
script
style
switch
text
view
Attributes:
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
presentation attributes
DOM Interfaces:
SVGDefsElement
The
defs
element is a container element for
referenced elements
. For understandability and
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
element; thus, any element that can be a child of a
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.
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:
animation elements
animate
animateMotion
animateTransform
set
descriptive elements
desc
title
metadata
paint server elements
linearGradient
radialGradient
pattern
shape elements
circle
ellipse
line
path
polygon
polyline
rect
structural elements
defs
svg
symbol
use
clipPath
filter
foreignObject
image
marker
mask
script
style
switch
text
view
Attributes:
aria attributes
aria-activedescendant
aria-atomic
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-level
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
role
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
presentation attributes
preserveAspectRatio
viewBox
refX
refY
Geometry properties:
width
height
DOM Interfaces:
SVGSymbolElement
The
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
| left | center | right
(none)
yes
refY
| 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
and
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
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:
animation elements
animate
animateMotion
animateTransform
set
descriptive elements
desc
title
metadata
clipPath
mask
script
style
Attributes:
aria attributes
aria-activedescendant
aria-atomic
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-level
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
role
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
conditional processing attributes
requiredExtensions
systemLanguage
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
presentation attributes
deprecated xlink attributes
xlink:href
xlink:title
href
Geometry properties:
width
height
DOM Interfaces:
SVGUseElement
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
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
and
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 and
data URL
resource requests in
use
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
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
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 further 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
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
and
properties define
an additional transformation
translate(x,y)
where
and
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
and
to position the graphics,
authors can nest the
use
element inside a
and apply the graphical effects to the
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:
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
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
(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).
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 apply 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.
Example Use-visibility-hidden, default styles
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,
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:
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:
conditional processing affects the visual display of
graphics elements
foreignObject
, and
text content elements
conditional processing prevents
animation elements
from playing.
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.
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:
animation elements
animate
animateMotion
animateTransform
set
shape elements
circle
ellipse
line
path
polygon
polyline
rect
foreignObject
image
svg
switch
text
use
Attributes:
aria attributes
aria-activedescendant
aria-atomic
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-level
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
role
conditional processing attributes
requiredExtensions
systemLanguage
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
presentation attributes
DOM Interfaces:
SVGSwitchElement
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
, 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 reference
s 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:
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).
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 (
) 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 markup 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:
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
DOM Interfaces:
SVGTitleElement
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:
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
DOM Interfaces:
SVGDescElement
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:
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
DOM Interfaces:
SVGMetadataElement
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.)
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:
the
base
element
the
link
element
the
meta
element
the
style
element
the
script
element
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:
Application-specific information so that authoring
applications can include model-level data in the SVG content
to serve their "roundtripping" purposes (i.e., the ability to
write, then read a file without loss of higher-level
information).
Supplemental data for extensibility. For example, suppose
there is an extension which extrudes 2D graphics
into three dimensions according to certain parameters;
these parameters may be included in the SVG content
by inserting elements from the extension's
namespace.
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:
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
aria-atomic
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-level
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
role
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
link
role
if the element has a valid
href
or
xlink:href
attribute.
For
elements that are not links, the default semantics are the same as
tspan
if the
element is a descendent of
text
or the same as
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
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
group
role,
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
SameObject
] readonly attribute
SVGAnimatedLength
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
();
NewObject
SVGNumber
createSVGNumber
();
NewObject
SVGLength
createSVGLength
();
NewObject
SVGAngle
createSVGAngle
();
NewObject
DOMPoint
createSVGPoint
();
NewObject
DOMMatrix
createSVGMatrix
();
NewObject
DOMRect
createSVGRect
();
NewObject
SVGTransform
createSVGTransform
();
NewObject
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
width
and
height
IDL attributes
reflect
the computed values of the
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:
If the current
svg
element is not the
outermost svg element
then return 1.
Let [
be the 2x3 matrix that represents the document's magnification and panning
transform.
Return
On setting
currentScale
the following steps are run:
If the current
svg
element is not the
outermost svg element
then return.
Let
scale
be the value being assigned to
currentScale
Let [
be the 2x3 matrix that represents the document's magnification and panning
transform.
Set the document's magnification and panning transform to
scale
0 0
scale
].
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:
Let [
be the 2x3 matrix that represents the document's magnification and panning
transform.
Let
element
be the
outermost svg element
Update the x and y components of
element
's
current translate point object
to
and
, 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:
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:
If
child
is an
svg
or
element, then:
Let
descendants
be the result of
finding the
intersecting (or enclosed) descendants
of
child
with
rectangle
in
ancestor
's coordinate space.
Append to
result
all the elements of
descendants
Otherwise, if
child
is a
use
element, then:
Let
root
be the root of the
child
's shadow tree.
Let
descendants
be the result of
finding the
intersecting (or enclosed) descendants
of
root
with
rectangle
in
ancestor
's coordinate space.
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.
Otherwise, if
child
is a
graphics element
, then:
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
element,
then for each child element
child
of
element
in document order:
Let
descendants
be the result of
finding the non-container
graphics elements
within
child
Append to
result
all the elements of
descendants
Otherwise, if
element
is a
graphics element
then
append
element
to
result
Return
result
When getIntersectionList(
rect
referenceElement
) or
getEnclosureList(
rect
referenceElement
) is called,
the following steps are run:
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.
If
referenceElement
is not null, then remove from
descendants
any element that does not have
referenceElement
as an ancestor.
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:
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.
Let
elements
be the result of
finding the non-container
graphics elements
within
element
If
elements
is empty, then return false.
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. [
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:
Method
Object and details
createSVGNumber
A new,
detached
SVGNumber
object whose value is 0.
createSVGLength
A new,
detached
SVGLength
object whose value is the unitless
0.
createSVGAngle
A new,
detached
SVGAngle
object whose value is the unitless
0.
createSVGPoint
A new,
detached
DOMPoint
object whose coordinates are all 0.
createSVGMatrix
A new,
detached
DOMMatrix
object representing the identity matrix.
createSVGRect
A new,
DOMRect
object whose x, y, width and height are all 0.
createSVGTransform
A 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
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
SameObject
] readonly attribute
SVGAnimatedLength
SameObject
] readonly attribute
SVGAnimatedLength
width
SameObject
] readonly attribute
SVGAnimatedLength
height
SameObject
] readonly attribute
SVGElement
instanceRoot
SameObject
] readonly attribute
SVGElement
animatedInstanceRoot
};
SVGUseElement
includes
SVGURIReference
The
width
and
height
IDL attributes
reflect
the computed values of the
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
interface 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
Constructor
Animation
source,
Animatable
newTarget), Exposed=Window]
interface
ShadowAnimation
Animation
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.
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.