Scalable Vector Graphics (SVG) 2

Scalable Vector Graphics (SVG) 2
Scalable Vector Graphics (SVG) 2
W3C Editor’s Draft
14 September 2025
This version:
Latest version:
Previous version:
Single page version:
GitHub repository:
Public comments:
www-svg@w3.org
archive
Editors:
Amelia Bellamy-Royds, Invited Expert <
amelia.bellamy.royds@gmail.com
Tavmjong Bah, Invited Expert <
tavmjong@free.fr
Chris Lilley, W3C <
chris@w3.org
Dirk Schulze, Adobe Systems <
dschulze@adobe.com
Eric Willigers, Google
Former Editors:
Nikos Andronikos, Canon, Inc. <
nikos.andronikos@cisra.canon.com.au
Rossen Atanassov, Microsoft Co. <
ratan@microsoft.com
Brian Birtles, Mozilla Japan <
bbirtles@mozilla.com
Bogdan Brinza, Microsoft Co. <
bbrinza@microsoft.com
Cyril Concolato, Telecom ParisTech <
cyril.concolato@telecom-paristech.fr
Erik Dahlström, Invited Expert <
erik@dahlström.net
Cameron McCormack, Mozilla Corporation <
cam@mcc.id.au
David Storey, Microsoft Co. <
dstorey@microsoft.com
Doug Schepers, W3C <
schepers@w3.org
Richard Schwerdtfeger, IBM <
schwer@us.ibm.com
Satoru Takagi, KDDI Corporation <
sa-takagi@kddi.com
Jonathan Watt, Mozilla Corporation <
jwatt@jwatt.org
W3C
MIT
ERCIM
Keio
Beihang
). W3C
liability
trademark
and
document use
rules apply.
Abstract
This specification defines the features and syntax for Scalable
Vector Graphics (SVG) Version 2. SVG is a language based on XML for describing
two-dimensional vector and mixed vector/raster graphics. SVG content is stylable,
scalable to different display resolutions, and can be viewed stand-alone,
mixed with HTML content, or embedded using XML namespaces within other XML languages.
SVG also supports dynamic changes; script can be used to create interactive documents,
and animations can be performed using declarative animation features or by using script.
Status of This Document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current W3C
publications and the latest revision of this technical report can be found in
the
W3C technical reports index
at https://www.w3.org/TR/
This document is the 14 September 2025
Editor’s Draft
of SVG 2. This version of SVG
builds upon
SVG 1.1 Second Edition
by improving the usability of the language and by adding new features commonly
requested by authors. The
Changes
appendix lists all
of the changes that have been made since SVG 1.1 Second Edition.
Comments on this Editor’s Draft are welcome.
Comments can be sent to
www-svg@w3.org
the public email list for issues related to vector graphics on the Web. This list is
archived
and
senders must agree to have their message publicly archived from their
first posting. To subscribe send an email to
www-svg-request@w3.org
with
the word
in the subject line.
The specification includes a number of annotations that the Working Group is
using to record links to meeting minutes and resolutions where specific decisions
about SVG features have been made. Different coloring is also used to mark the
maturity of different sections of the specification:
a red background indicates a section that is either unchanged since SVG
1.1 (and which therefore still requires review and possible rewriting for
SVG 2), or a section that is new but still requires substantial work
a yellow background indicates a section from SVG 1.1 that has been reviewed
and rewritten if necessary, or a new section that is complete and ready
for the rest of the Working Group to review
a white background indicates a section, either from SVG 1.1 or new for
SVG 2, that has been reviewed by the Working Group and which is ready
for wider review
This document has been produced by the
W3C SVG Working Group
as part of
the
Graphics Activity
within
the
W3C Interaction Domain
. The
goals of the W3C SVG Working Group are discussed in the
W3C SVG Charter
The W3C SVG Working Group maintains a public Web page,
that contains further background information. The authors of
this document are the SVG Working Group participants.
This document was produced by a group operating under the
5 February 2004 W3C Patent Policy
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of the group; that page also includes
instructions for disclosing a patent. An individual who has actual knowledge of
a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy
Publication as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents
at any time. It is inappropriate to cite this document as other than work in progress.
A list of current W3C Recommendations and other technical documents can be found at
. W3C publications
may be updated, replaced, or obsoleted by other documents at any time.
This document is governed by the
1 September 2015 W3C Process Document
All features in this specification depend upon implementation in browsers
or authoring tools. If a feature is not certain to be implemented, we define
that feature as "at risk". At-risk features will be removed from the current
specification, and may be included in future versions of the specification. If
an at-risk feature is particularly important to authors of SVG, those authors
are encouraged to give feedback to implementers regarding its priority. The
following features are at risk, and may be dropped during the CR period:
More than one
title
or
desc
to provide localisation
Nested links
vector-effect
options other than
non-scaling-stroke
stroke-linejoin
options
miter-clip
and
arcs
the
shape-inside
and
shape-subtract
properties
Acknowledgments
The SVG Working Group would like to thank the following people for
contributing to this specification with patches or by participating in discussions
that resulted in changes to the document:
David Dailey,
Eric Eastwood,
Jarek Foksa,
Daniel Holbert,
Paul LeBeau,
Robert Longson,
Henri Manson,
Ms2ger,
Kari Pihkala,
Philip Rogers,
David Zbarsky.
In addition, the SVG Working Group would like to acknowledge the
contributions of the editors and authors of the previous versions
of SVG – as much of the text in this document derives from these
earlier specifications – including:
Patrick Dengler, Microsoft Corporation
(Version 1.1 Second Edition)
Jon Ferraiolo, ex Adobe Systems
(Versions 1.0 and 1.1 First Edition; until 10 May 2006)
Anthony Grasso, ex Canon Inc.
(Version 1.1 Second Edition)
Dean Jackson, ex W3C
(Version 1.1 First Edition; until February 2007)
藤沢 淳 (FUJISAWA Jun), Canon Inc.
(Version 1.1 First Edition)
Finally, the SVG Working Group would like to acknowledge the
great many people outside of the SVG Working Group who help with the
process of developing the SVG specifications. These people are too
numerous to list individually. They include but are not limited to
the early implementers of the SVG 1.0 and 1.1 languages (including
viewers, authoring tools, and server-side transcoders), developers of
SVG content, people who have contributed on the
www-svg@w3.org
and
svg-developers@yahoogroups.com
email lists, other Working Groups at the
W3C, and the W3C Team. SVG 1.1 is truly a cooperative effort between
the SVG Working Group, the rest of the W3C, and the public and benefits
greatly from the pioneering work of early implementers and content
developers, feedback from the public, and help from the W3C team.
Chapter 1: Introduction
1.1. About SVG
This specification defines the features and syntax for
Scalable Vector Graphics (SVG)
SVG is a language for describing two-dimensional graphics.
As a standalone format or when mixed with other XML, it uses the
XML syntax [
xml
].
SVG code used inside HTML documents uses the HTML syntax [
HTML
].
SVG allows for three types of graphic objects: vector graphic
shapes (e.g., paths consisting of straight lines and curves),
images and text. Graphical objects can be grouped, styled,
transformed and composited.
The feature set includes nested transformations, clipping
paths, alpha masks, filter effects and template objects.
SVG drawings can be
interactive
and
dynamic
Animations
can be defined and triggered
either declaratively (i.e., by embedding SVG animation elements
in SVG content) or via scripting.
Sophisticated applications of SVG are possible by use of a
supplemental scripting language which accesses
SVG Document Object Model (DOM)
, which
provides complete access to all elements, attributes and
properties. A rich set of
event handlers
can be assigned to any SVG graphical object.
Within a web page, the same scripts can work on both HTML and SVG elements.
Scripting
SVG is useful for rich graphical presentation of information, including a number
of
accessibility features that, used correctly
ensure the content can be used by the widest possible audience. But a direct
link to source data, where possible,
is helpful for many people to understand the content provided.
1.2. Compatibility with other standards efforts
SVG leverages and integrates with other W3C specifications
and standards efforts, as described in the following:
SVG can be integrated with
HTML
either by using SVG in HTML or by using HTML in SVG, in both cases either by inclusion or reference.
SVG is an application of XML and is compatible with
XML 1.0
and with the
Namespaces in XML
specification. However, when SVG content is included in HTML document, the HTML syntax applies and may not be compatible with XML. See
SVG Integration
for details.
SVG content is styled with CSS. See
Styling with CSS
for details.
SVG includes a complete Document Object Model (DOM) and
extends
DOM4
The SVG DOM has a high level of compatibility and consistency
with the HTML DOM.
Additionally, the SVG DOM supports and
incorporates many of the facilities described in
the CSS object model and event handling
dom-level-2-style
uievents
].
SVG incorporates some features and approaches that are
part of
SMIL 3
, including
the
switch
element and the
systemLanguage
attribute.
SVG is compatible with W3C work on internationalization.
References (W3C and otherwise) include: [
UNICODE
and [
charmod
].
SVG is compatible with
W3C work on Web Accessibility
See
Accessibility Support
1.3. Relationship to previous versions of this standard
This edition of the SVG standard has been developed based on, and built upon, the 1.1 edition released in 2003.
An intermediate version of SVG - named
Tiny 1.2
- was released
in 2008. However it did not receive wide acceptance and there have been very few implementations of its
enhanced feature set. However there are some 1.2 features that have been implemented by many SVG implementations and
those have been incorporated as part of this specification. But otherwise, the SVG Working Group consider version
Tiny 1.2 to be a deprecated branch of the SVG standard.
1.4. Normative Terminology
Within this specification, the key words "MUST", "MUST NOT",
"REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as
described in
Key words for use in RFCs to Indicate Requirement Levels
rfc2119
].
However, for readability, these words do not appear in all
uppercase letters in this specification.
At times, this specification recommends good practice for
authors and user agents.
Chapter 2: Conformance Criteria
2.1. Overview
Graphics defined with SVG have many different applications.
As a result, not all software that uses SVG will have the same features.
Conformance to the SVG specification is therefore not a binary matter;
software may be conforming within a restricted feature set.
Furthermore, SVG is designed to be integrated into other types of documents;
depending on the type of integration, only a limited feature-set may be appropriate.
There are various ways that an SVG document fragment can be
referenced by or included in other documents and thereby
be processed by a user agent. SVG documents can also be viewed directly,
as the primary document.
Each different method by which an SVG document fragment
can be used implies a certain set of requirements on how the SVG document
fragment must be processed.
This chapter therefore defines a number of
processing modes
that encompass the different combinations of features
which may be enabled or disabled in the document.
In addition, it specifies normative requirements for which processing mode
must be used when SVG documents reference or embed other SVG documents.
The same set of processing modes may be used by reference in other specifications
to describe how SVG documents should be processed.
This document does not place normative requirements on
other specifications that can reference or include SVG documents, such as
HTML and various CSS specifications. The intention is for these other
specifications to normatively point to the appropriate processing mode
from this document.
This chapter also outlines specific conformance requirements
for
different types of SVG content
and
different classes of software
that use or create SVG.
2.2. Processing modes
This section defines a standard set of
processing modes
for SVG documents. Each processing mode specifies whether certain high level
SVG features are enabled.
2.2.1. Features
The features that can be enabled or disabled depending
on the processing mode are as follows:
declarative animation
Declarative animation includes both the animation elements in SVG –
animate
animateMotion
animateTransform
and
set
– and CSS Transitions and Animations
(see the
Animation appendix
for details).
When declarative animations are disabled in an SVG document, any
animation elements or CSS Transitions or Animations must not be applied or run.
This is not the same as pausing the document's animated
state at 0s document time; if an animation is defined to begin at 0s,
it still will not be applied.
references to external resources
References to
external resources
are URLs references
or network access requests
made by markup, style properties, script or other Web platform features
used in the document, except for:
same-document URL references
, as defined in the
Linking chapter
data URL references
, as defined by
the "data" URL scheme
rfc2397
When external references are disabled in an SVG document, any attempt to
fetch a document through an external reference must instead be treated as
if a network error occurred and no data was received.
When external references are enabled,
user agents that support external file requests from the Internet
must adhere to the restrictions on cross-origin resource fetching,
as outlined in
the Linking chapter
script execution
Script execution is the execution of any SVG
script
elements,
script found in
event attributes
(such as
onclick
on
SVG elements), or any other script defined by other Web platform features
used in the document, such as any HTML
script
elements.
When script execution is disabled in an SVG document, no script in the
document must be run.
interaction
Interaction refers to the delivery of DOM Events or the invocation of
any user agent specific UI behaviors such as text selection, focus changing,
link traversal, or animation or transition triggering that is done in
response to user input such as mouse or keyboard activity. When
interaction is disabled in an SVG document, any user input events that would
be targetted at the document or any elements within the document must have
no effect.
2.2.2. Dynamic interactive mode
This
processing mode
imposes no restrictions on any
feature of the SVG language.
Dynamic Interactive Features
script execution
yes
external references
yes
declarative animation
yes
interactivity
yes
2.2.3. Animated mode
This
processing mode
is intended for circumstances where
an SVG document is to be used as an animated image that is allowed
to resolve external references, but which is not intended to be used
as an interactive document.
Animated Features
script execution
no
external references
yes
declarative animation
yes
interactivity
no
2.2.4. Secure animated mode
This
processing mode
is intended for circumstances where
an SVG document is to be used as an animated image that is not allowed
to resolve external references, and which is not intended to be used
as an interactive document. This mode might be used where image support
has traditionally been limited to raster images (such as JPEG, PNG and
GIF).
Secure Animated Features
script execution
no
external references
no
declarative animation
yes
interactivity
no
2.2.5. Static mode
This
processing mode
is intended for circumstances where
an SVG document is to be used as a non-animated image that is allowed
to resolve external references, but which is not intended to be used
as an interactive document.
For example,
an SVG viewer that processes graphics for inclusion in print documents
would likely use static mode.
Static Features
script execution
no
external references
yes
declarative animation
no
interactivity
no
2.2.6. Secure static mode
This
processing mode
is intended for circumstances where
an SVG document is to be used as a non-animated image that is not allowed
to resolve external references, and which is not intended to be used
as an interactive document. This mode might be used where image support
has traditionally been limited to non-animated raster images (such as JPEG
and PNG.)
Secure Static Features
script execution
no
external references
no
declarative animation
no
interactivity
no
2.3. Processing modes for SVG sub-resource documents
When an SVG document is viewed directly,
it is expected to be displayed using the most comprehensive
processing mode
supported by the user agent.
However, when an SVG is processed
as a sub-resource or embedded document,
the following restrictions must apply:
image
references
An SVG embedded within an
image
element
must be processed in
secure animated mode
if the embedding document supports
declarative animation
or in
secure static mode
otherwise.
The same processing modes are expected to be used
for other cases where SVG is used in place of a raster image,
such as an HTML
‘img’
element or
in any CSS property that takes an

data type.
This is consistent with
HTML's requirement
that image sources must reference
"a non-interactive, optionally animated, image resource that is neither paged nor scripted"
HTML
use
element and other
'href'
references
When SVG documents are loaded
through
use
element references
or
paint server element
cross-references
they must be processed in
secure static mode
Note that animations do not run while processing the sub-resource document,
for both performance reasons and because there is currently no context
defined for resource documents to reference their timeline against.
However, when elements from a sub-resource document are cloned
into the current document because of a
use
element reference
or paint-server cross-reference,
the cloned
element instances
may be animated
in the current document's timeline,
as described in
Animations in use-element shadow trees
and may trigger the loading of additional sub-resource files.
Graphical effects references
When SVG documents are loaded
through any style property references that target specific elements in the document
(as opposed to SVG as an image format),
they must be processed in
secure static mode
Note that animations do not run in sub-resource documents,
for both performance reasons and because there is currently no context
defined for resource documents to reference their timeline against.
Some style properties may reference either specific elements
or entire image files;
the processing mode is more restrictive in the first case.
For example, a reference to an SVG
mask
element
will not be animated,
but an entire SVG file used as an image mask can be.
SVG in fonts
When SVG files are processed as part of a font reference,
they must use the
secure animated mode
if animated glyphs are supported,
or
secure static mode
otherwise.
These restrictions are included in the
OpenType specification for processing documents from the "SVG"
table.
OpenType also applies additional restrictions,
in the form of a
user agent style sheet
that prevents rendering of text and foreign objects
OPENTYPE
].
SVG document fragments that are included inline in a host document
must use a
processing mode
that matches that of the host document.
SVG document fragments included as
children of an SVG
foreignObject
element must use the
processing mode
of the surrounding SVG document;
non-SVG foreign content must be processed with equivalent restrictions.
For example, if an SVG document is being used in
secure animated mode
due to being referenced
by an HTML
‘img’
or SVG
image
element,
then any content within a
foreignObject
element
must have scripts, interactivity, and external file references disabled,
but should have declarative animation enabled.
2.3.1. Examples
Below are various methods of embedding SVG in an HTML page by
reference,
along with the expected processing mode
and allowed features for each.
Each cell in the "Live Example" row should display a yellow
smiley face.
In each example below, clicking on the eyes tests link
traversal,
and clicking on the face tests declarative interactivity
and script execution.
The link should replace the image with a blue
square (clicking it will revert it to the original image).
The declarative interactivity
uses the
set
element to change the face from shades of yellow to shades of green,
and uses CSS pseudoclasses to add a stroke to the interactive elements.
The script should fill in the smile.
Time-based (as opposed to interactivity-based) declarative animation is supported if the left eye is winking (using the
animate
element)
and if the eyes are dark blue with regular flashes of light blue (using CSS keyframe animation).
The expected processing modes and features outlined here
are subject to any future changes in the corresponding HTML or CSS specification.
Embedding method
object without sandboxing
img
CSS background
Expected processing mode
dynamic interactive
dynamic interactive, with restrictions
secure animated
secure animated
Declarative, time-based animation
(winking left eye, color-change in both eyes)
allowed
allowed
allowed
allowed
Declarative, interactive animation and style changes
(face color changes when clicked, face/eyes outlined when hovered or focused)
allowed
allowed
disabled
disabled
Link navigation within the same browsing context, to the same domain
(image changes when clicking eyes)
allowed
allowed
disabled
disabled
Scripted interaction
(smile widens when clicking face)
allowed
disabled (because of sandboxing)
disabled
disabled
Live example
This browser does not support embedded SVG images.
2.4. Document Conformance Classes
SVG is defined in terms of a document object model (DOM),
rather than a particular file format or document type.
For SVG content, therefore,
conformance with this specification is defined by whether
the content is or can generate a conforming DOM.
Additional conformance classes depend on whether the content
is also valid and well-formed XML [
xml
].
2.4.1. Conforming SVG DOM Subtrees
A DOM node tree or subtree rooted at a given element
is a
conforming SVG DOM subtree
if it forms a
SVG document fragment
that adheres to the specification described in this document
Scalable Vector Graphics (SVG) Specification
).
Specifically, it:
is rooted by an
svg
element in the
SVG namespace
conforms to the content model and attributes rules for the elements defined in this document (
Scalable Vector Graphics (SVG) Specification
), and
conforms to the content model and attributes rules defined
by other specifications for any elements in the
SVG namespace
defined by those specifications
(including:
filter-effects-1
],
css-masking-1
],
svg-animation
]).
SVG document fragments can be included within parent XML documents using
the XML namespace facilities described in
Namespaces in XML
xml-names
].
Note, however, that since a conforming SVG DOM subtree must have an
svg
element as its root, the use of an individual non-
svg
element from the SVG namespace is disallowed. Thus, the SVG part of the
following document is
not
conforming:





x="0" y="0" width="10" height="10" />


Instead, for the SVG part to become a
conforming SVG DOM subtree
the file could be modified as follows:





width="100px" height="100px">




The SVG language and these conformance criteria provide no designated
size limits on any aspect of SVG content. There are no maximum values on
the number of elements, the amount of character data, or the number of
characters in attribute values.
2.4.2. Conforming SVG Markup Fragments
A document or part of a document is a
conforming SVG markup fragment
if it can be parsed without error (other than network errors)
by the appropriate parser for the document MIME type
to form a
conforming SVG DOM subtree
and in addition if:
any CSS stylesheets included in the document
conform to the core grammar of
Cascading Style Sheets, level 2 revision 1
CSS2
].
2.4.3. Conforming XML-Compatible SVG Markup Fragments
conforming SVG markup fragment
is also a
conforming XML-compatible SVG markup fragment
if it:
meets all
XML well-formedness constraints
([
xml
]),
conforms to the
Namespaces in XML
specification [
xml-names
],
all
id
attributes are
valid XML IDs
([
xml
], section 3.3.1), and
any

processing instruction conforms to
Associating stylesheets with XML documents
xml-stylesheet
].
2.4.4. Conforming XML-Compatible SVG DOM Subtrees
A DOM node tree or subtree rooted at a given element
is an
conforming XML-compatible SVG DOM subtree
if, once serialized to XML,
it could form a
conforming XML-compatible SVG markup fragment
If the DOM subtree cannot be serialized to conforming XML without altering it,
such as when an
id
value is not a valid XML name, or when a
Comment
node's data contains the substring "--", then the subtree is not
a conforming XML-compatible SVG DOM subtree.
2.4.5. Conforming SVG Stand-Alone Files
A document is a
conforming SVG stand-alone file
if:
it is a well-formed XML document,
its root element is an
svg
element,
the SVG document fragment rooted at the document element is a
conforming XML-compatible SVG markup fragment
, and
any other
SVG document fragments
within the document
(such as those within a
foreignObject
form a
conforming XML-compatible SVG markup fragment
2.4.6. Error processing
There are various scenarios where an SVG document fragment
is technically
in error
The document or DOM subtree is not-conforming for its document type,
as described in the previous sections.
Other situations that are described as being
in error
in this
specification, such as incorrect attribute values.
A dynamic document can go in and out of error over time. For
example, document changes from the
SVG DOM
or from
animation
can cause
a document to become
in error
and a further change can
cause the document to become correct again.
User agents must use the following error processing rules whenever a document
is in error,
unless other sections of this specification define more specific rules for handling the particular error type:
The document rendering shall continue after encountering element which has an error. The element or its part that is in error won't be rendered.
If the user agent has access to an error reporting
capability such as status bar or console, it is recommended that the
user agent provide whatever additional detail it can to
enable the user or developer to quickly find the source of
the error. For example, the user agent might provide an error
message along with a line number and character number at
which the error was encountered.
Because of situations where a block of scripting changes
might cause a given SVG document fragment to go into and out of
error, the user agent should only apply error processing at times when document
presentation (e.g., rendering to the display device) is
updated.
2.5. Software Conformance Classes
For software, the requirements for conformance depend
on the category of program:
SVG generators
Any software that creates or makes available SVG content,
either as markup or as a DOM
(as is the case with client-side JavaScript libraries).
SVG authoring tools
Any software that provides an interface for human content creators
to manipulate graphics or code that will be used to generate SVG.
SVG authoring tools are implicitly also
SVG generators
SVG servers
Any network or file server that makes available SVG content
in response to requests from other software.
SVG servers are implicitly also
SVG generators
SVG interpreters
Any software that parses or processes SVG documents or markup fragments.
An SVG interpreter is an
SVG user agent
for the purpose of any sections of this specification that
relate to the parsing or processing steps undertaken by the interpreter.
SVG viewers
Any software that creates a rendered graphical representation
after parsing or processing an SVG document or SVG markup fragment.
SVG viewers are implicitly also
SVG interpreters
An SVG viewer is always an
SVG user agent
for the purpose of this specification.
SVG user agent
An SVG user agent is a
user agent
that is able to retrieve and
render SVG content.
user agent
The general definition of a user agent is an application
that retrieves and renders Web content, including text,
graphics, sounds, video, images, and other content types. A
user agent may require additional user agents that handle
some types of content. For instance, a browser may run a
separate program or plug-in to render sound or video. User
agents include graphical desktop browsers, multimedia
players, text browsers, voice browsers, and assistive
technologies such as screen readers, screen magnifiers,
speech synthesizers, onscreen keyboards, and voice input
software.
In general terms,
a "user agent" may or may not have the ability to retrieve
and render SVG content;
however, unless the context requires an alternative interpretation,
all references to a "user agent" in this specification
are assumed to be references to an
SVG user agent
that
retrieves and renders SVG content.
Many programs will fall under multiple software classes.
For example, a graphical editor that can import and display SVG files,
allow the user to modify them,
and then export the modified graphic to file,
is an SVG interpreter,
an SVG viewer,
an SVG authoring tool,
and an SVG generator.
2.5.1. Conforming SVG Generators
conforming SVG generator
is a
SVG generator
that:
always creates
conforming SVG DOM subtree
conforming SVG markup fragment
or a
conforming SVG stand-alone file
does not create documents containing non-conforming SVG document fragments;
meets all normative requirements in this specification for SVG authors,
as well as specific normative requirements for SVG generators.
SVG generators are strongly encouraged to
use a Unicode character encoding by default,
and to follow the other guidelines of the
Character Model for the World Wide Web
UNICODE
charmod
].
SVG generators handling high-precision data
are encouraged to follow the guidelines in the section
Notes on generating high-precision geometry
2.5.2. Conforming SVG Authoring Tools
An
authoring tool
as defined in the
Authoring Tool Accessibility
Guidelines 2.0
is a
conforming SVG authoring tool
if it is a
conforming SVG generator
and it also conforms to all relevant Level A requirements from that document
atag20
].
Level AA and Level AAA requirements are
encouraged but not required for conformance.
2.5.3. Conforming SVG Servers
conforming SVG server
must meet all the requirements of a
conforming SVG generator
. In addition, conforming SVG servers using HTTP or other protocols
that use Internet Media types must serve SVG stand-alone files with the media
type
"image/svg+xml"
Also, if the SVG file is compressed with gzip or deflate, conforming SVG
Servers must indicate this with the appropriate header, according to what the
protocol supports. Specifically, for content compressed by the server
immediately prior to transfer, the server must use the "Transfer-Encoding: gzip"
or "Transfer-Encoding: deflate" headers as appropriate.
For content stored in a compressed format on the server (e.g. with the file extension
.svgz
),
the server must use the "Content-Encoding: gzip" or
"Content-Encoding: deflate" headers as appropriate.
In HTTP, compression of stored
content
(the "entity") is distinct from automatic compression of the
message body
, as
defined in HTTP/1.1
TE
Transfer Encoding
([
rfc2616
], sections 14.39 and 14.41).
If this is poorly configured,
and the compression specified in the HTTP headers does not match the used values,
SVG user agents
are required to treat the document as being in error
Configuring a server to handle both SVG and SVGZ files
means that it must be able to assign the same media type to both types of files,
but with different compression headers.
Some commonly used servers do not support this configuration in an easy or efficient way,
because compression behavior is configured based on media type.
With most modern web servers, it is often easier to upload uncompressed SVG files instead of SVGZ files.
Then, rely on the server to compress the file for transmission,
and cache it for future request,
using the same server instructions as for other text-based file formats such as HTML.
This also allows the server to use newer compression methods,
when they are supported by the user agent requesting the file.
Alternatively, the web server may be able to correctly process pre-compressed SVGZ files
if they are first renamed to use the
.svg.gz
compound file extension.
The server would still need to be configured to support static gzip-compressed files.
2.5.4. Conforming SVG Interpreters
An
SVG interpreter
is a program which can parse and process
SVG document fragments. Examples of SVG interpreters are
server-side transcoding tools or optimizers (e.g., a tool which converts SVG
content into modified SVG content) or analysis tools (e.g., a
tool which extracts the text content from SVG content,
or a validity checker).
A transcoder from SVG into another graphics
representation, such as an SVG-to-raster transcoder, represents
a viewer, and thus viewer conformance criteria also apply.
conforming SVG interpreter
must be able to parse and process all
XML constructs defined in
XML 1.0
xml
] and
Namespaces in XML
xml-names
].
conforming SVG interpreter
must parse any
conforming XML-compatible SVG markup fragment
in a manner that correctly respects the DOM structure
(elements, attributes, text content, comments, etc.) of the content.
The interpreter is not required to interpret the semantics of all
features correctly.
If the SVG interpreter supports non-XML syntaxes (such as HTML),
it must correctly parse any
conforming SVG markup fragment
in that syntax.
If the SVG interpreter runs scripts or fetches external resource files
as a consequence of processing the SVG content,
it must follow the restrictions described for
user agents
in
Processing modes for SVG sub-resource documents
and in the
Linking chapter
2.5.5. Conforming SVG Viewers
Action:
Look at the performance class requirements and decide whether to remove points or move them into general requirements.
(heycam)
Spec that calculation of CTMs should use double precision.
(stakagi)
Resolution:
Remove performance class requirements from SVG 2.
ConformingHighQualitySVGViewers
Purpose:
To modulate the tradeoff of a numerical precision in use cases of the technical drawing and mapping, and the performance of user agent.
Owner:
heycam, stakagi
An
SVG viewer
is a program which can parse and process an
SVG document fragment and render the contents of the document
onto some sort of graphical output medium such as a display, printer, or engraver.
Thus, an
SVG viewer
is also an
SVG interpreter
(in that it can parse and process SVG document fragments),
but with the additional requirement of correct rendering.
conforming SVG viewer
must be a
conforming SVG interpreter
, and
must be able to support rendering output in at least one of the
processing modes defined in this chapter:
dynamic interactive mode
animated mode
secure animated mode
static mode
secure static mode
A conforming SVG viewer must meet all normative requirements
indicated in this specification for
user agents
for all features supported by its processing mode(s).
Specific criteria that must apply to all
conforming SVG viewers
The viewer must be able to parse all CSS syntax features
defined in
Cascading Style Sheets, level 2 revision 1
CSS2
],
and must support CSS styling of SVG content including
all
required properties
and
required features
listed in the
Styling
chapter.
The viewer may support other CSS language features,
and any other properties that are defined by the corresponding specification to apply to SVG elements.
The supported features from CSS 2.1 must be implemented in accordance with
the
conformance
definitions from the CSS 2.1 specification
([
CSS2
], section 3.2).
The viewer must be able to apply
styling properties to SVG content using
presentation attributes
Areas of an image of SVG content may have opacity less than 100%.
The viewer must at least support Simple Alpha Compositing
of the image of the SVG content onto the target canvas, as described in the
Compositing and Blending Specification
compositing-1
].
The viewer must support
data URL references
containing base64-encoded or URL-encoded content,
in conformance with
the "data:" URL scheme
rfc2397
],
wherever a URI reference to another document is permitted within
SVG content.
When the encoded document is of MIME type
image/svg+xml
it must be a well-formed, complete SVG document in order to be processed.
The viewer must support JPEG and PNG
image formats [
JPEG
] [
PNG
].
Even if the viewer only supports secure processing modes,
it is still required to support these image formats,
in order to process
data URL references
Resampling of image data must be consistent with the
specification of property
image-rendering
Whenever possible in the parent environment,
the viewer must use information about physical device resolution
and expected viewing conditions in order to accurately
determine the initial scale
in conformance with
the rules described in CSS 2.1
([
CSS2
], section 4.3.2).
In situations where this
information is impossible to determine,
the viewer or the parent environment must make a reasonable approximation
for common target devices.
All visual rendering must be accurate to within one
device pixel or point of the mathematically correct result
at the initial 1:1 zoom ratio. It is suggested that viewers
attempt to keep a high degree of accuracy when zooming.
On lower-resolution display devices,
support for anti-aliasing or other smoothing methods is highly recommended.
It is a requirement for
conforming high-quality SVG viewers
If printing devices are supported, SVG content must be
printable at printer resolutions with the same graphics
features available as required for display (e.g., the
specified colors must be rendered on color printers).
On systems which support accurate sRGB
SRGB
] color, all
sRGB color computations and all resulting color values must
be accurate to within one sRGB color component value, where
sRGB color component values range from 0 to 255.
SVG implementations must correctly support
gzip-encoded
rfc1952
] and
deflate-encoded
rfc1951
] data streams,
for any content type (including SVG, script files, images).
SVG implementations that support HTTP must support these
encodings according to the
HTTP 1.1
specification [
rfc2616
];
in particular, the client must specify with an "Accept-Encoding:"
request header [
HTTP-ACCEPT-ENCODING
those encodings that it accepts, including at minimum gzip
and deflate, and then decompress any
gzip-encoded
and
deflate-encoded
data streams that are downloaded from the server. When an SVG
viewer retrieves compressed content (e.g., an
.svgz
file) over
HTTP, if the "Content-Encoding" and "Transfer-Encoding" response
headers are missing or specify a value that does not match the
compression method that has been applied to the content, then
the SVG viewer must not render the content and must treat the
document as being
in error
The viewer must use at least single-precision floating point for intermediate calculations on any numerical operations for conversion of coordinates. However, in order to prevent the rounding error on coordinate transformation, at least double-precision floating point computation must be used on
CTM
generation processing. Such minimum typical computation way is expressed with following formulas.
single
CTM
single
double
double
$$
(single)
{\large \rm CTM} =
(single)
\left(
(double)
\left[
\begin{matrix}
a_1 & c_1 & e_1 \\
b_1 & d_1 & f_1 \\
0 & 0 & 1
\end{matrix}
\right]
\cdot
(double)
\left[
\begin{matrix}
a_2 & c_2 & e_2 \\
b_2 & d_2 & f_2 \\
0 & 0 & 1
\end{matrix}
\right]
\right)
$$
single
viewport
viewport
CTM
single
userspace
userspace
$$
(single)
\left[
\begin{matrix}
x_{\rm viewport} \\
y_{\rm viewport} \\
\end{matrix}
\right]
{\large \rm CTM} \cdot (single)
\left[
\begin{matrix}
x_{\rm userspace} \\
y_{\rm userspace} \\
\end{matrix}
\right]
$$
Furthermore, when it has nested viewport coordinate systems, the
ScreenCTM
which is a transformation matrix produced by nested CTM for transforming user coordinates into the coordinates of an output device also must be generated by double-precision floating point computation.
conforming SVG viewer
that supports
processing modes
that
include
interaction
must support the following additional features:
For interactive user environments, facilities must exist
for zooming and panning of stand-alone SVG documents or SVG
document fragments embedded within parent XML documents.
In environments that have appropriate user interaction
facilities, the viewer must support the ability to activate
hyperlinks.
In Web browser environments, the viewer must have the
ability to search and select text strings within SVG
content.
If display devices are supported, the viewer must have
the ability to select and copy text from SVG content to the
system clipboard.
The viewer must meet all applicable Level A requirements of the
User Agent Accessibility Guidelines 2.0
UAAG20
].
Level AA and level AAA features are encouraged,
but not required.
conforming SVG viewer
that supports
processing modes
that
include
script execution
must support the following additional features:
The viewer must be a
conforming ECMAScript implementation
of all the IDL fragments in this specification.
WebIDL
If the user agent includes an HTML or XHTML viewing
capability, or can apply CSS styling properties to XML
documents, then a
conforming SVG viewer
must support
resources of MIME type "image/svg+xml" wherever raster image
external resources can be used, such as in the HTML or XHTML
‘img’
element and in CSS
properties that can refer to raster image resources (e.g.,
background-image
’).
2.5.5.1. Printing implementation notes
For user agents which support both zooming on display
devices and printing, it is recommended that the default
printing option produce printed output that reflects the
display device's current view of the current SVG document
fragment (assuming there is no media-specific styling), taking
into account any zooming and panning done by the user, the
current state of animation, and any document changes due to DOM
and scripting.
Thus, if the user zooms into a particular area
of a map on the display device and then requests a hardcopy,
the hardcopy should show the same view of the map as appears on
the display device. If a user pauses an animation and prints,
the hardcopy should show the same graphics as the currently
paused picture on the display device. If scripting has added or
removed elements from the document, then the hardcopy should
reflect the same changes that would be reflected on the
display.
When an SVG document is rendered on a static-only device
such as a printer which does not support SVG's animation and
scripting and facilities, then the user agent shall ignore any
animation and scripting elements in the document and render the
remaining graphics elements according to the rules in this
specification.
2.5.6. Conforming High-Quality SVG Viewer
In order for a
conforming SVG viewer
to be considered
conforming high-quality SVG viewer
, it must
support the following additional features:
Professional-quality results with good processing and
rendering performance and smooth, flicker-free
animations.
On low-resolution devices such as display devices at
150dpi or less, support for smooth edges on lines, curves and
text. (Smoothing is often accomplished using anti-aliasing
techniques.)
Color management via ICC profile support
ICC
] (i.e., the
ability to support colors defined using ICC profiles)
css-color-4
Resampling of image data must conform to the requirements
for conforming high-quality SVG viewers as specified in the
description of property
image-rendering
At least double-precision floating point computation on
coordinate system transformation numerical calculations.
conforming high-quality SVG viewer
that supports
processing modes
that
include
script execution
declarative animation
, or
interaction
must support the following additional features:
Progressive rendering and animation effects (i.e., the
start of the document will start appearing and animations
will start running in parallel with downloading the rest of
the document).
Restricted screen updates (i.e., only required areas of
the display are updated in response to redraw events).
conforming high-quality SVG viewer
that supports
processing modes
that include
interaction
must support the following additional features:
Background downloading of images and fonts retrieved from
a Web server, with updating of the display once the downloads
are complete.
Chapter 3: Rendering Model
The SVG 2 rendering model will follow the rules defined by the
Compositing and Blending specification
Resolution:
Seattle/Paris 2012 F2F day 3
Owner: Nikos (Action 3332).
Status: Done.
3.1. Introduction
Implementations of SVG must implement the rendering model as described in this
chapter, as modified in the appendix on
conformance
requirements
which describes
situations where an implementation may deviate.
In practice variability is allowed based on limitations of the output device
(e.g. only a limited range of colors might be supported) and because of practical
limitations in implementing a precise mathematical model (e.g. for realistic
performance curves are approximated by straight lines, the approximation need
only be sufficiently precise to match the conformance requirements).
The appendix on
conformance
requirements
describes the extent to which an actual
implementation may deviate from this description. In practice
an actual implementation
may
deviate slightly because of
limitations of the output device (e.g. only a limited range of
colors might be supported) and because of practical limitations
in implementing a precise mathematical model (e.g. for
realistic performance curves are approximated by straight
lines, the approximation need only be sufficiently precise to
match the conformance requirements).
3.2. The rendering tree
The components of the final rendered representation of an SVG document
do not have a one-to-one relationship with the underlying
elements in the document model.
The appearance of the graphic instead reflects a parallel structure,
the rendering tree,
in which some elements are excluded and others are repeated.
Many elements in the SVG namespace do not directly represent
a component of the graphical document.
Instead, they define graphical effects, metadata,
content to be used to represent other elements,
or alternatives to be displayed under certain conditions.
In dynamic documents, certain components of the graphic
may be rendered or not, depending on interaction or animation.
These non-rendered elements are not directly included
in the
rendering tree
Because SVG supports the reuse of graphical sub-components,
some elements are rendered multiple times.
The individual renderings may have context-dependent styling
and may be rasterized at different scales or transformations.
3.2.1. Definitions
rendering tree
The rendering tree is the set of elements being rendered
in an
SVG document fragment
It is generated from the document tree
by excluding
non-rendered elements
and inserting additional fragments for
re-used graphics
Graphics are painted and composited in rendering-tree order,
subject to re-ordering based on the
paint-order
property.
Note that elements that have no visual paint may still be in the rendering tree.
rendered element
An element that has a direct representation in the
rendering tree
for the current document.
Includes a rendered
instance
of an element in a
use-element shadow tree
Does not include elements that affect rendering
as the source definition of re-used graphics
but are not directly rendered themselves.
See
Rendered versus non-rendered elements
non-rendered element
An element that does not have a direct representation in the
rendering tree
for the current document.
It may nonetheless affect the rendering tree as re-used graphics
or graphical effects.
See
Rendered versus non-rendered elements
re-used graphics
Graphical components that are included in the rendering tree
but do not have a single direct equivalent element
in the document model.
They may be represented through shadow DOM elements
(as in graphics re-used with a
use
element),
or as image fragments generated as part of a graphical effect
(as in patterns or masks).
never-rendered element
Any element type that is
never directly rendered
regardless of context or
display
style value.
It includes the following elements:
clipPath
defs
desc
linearGradient
marker
mask
metadata
pattern
radialGradient
script
style
and
title
it also includes a
symbol
element that is not
the
instance root
of a
use-element shadow tree
renderable element
Any element type that
can
have a direct representation
in the
rendering tree
as a graphic, container, text, audio, or animation.
It includes the following elements:
circle
ellipse
foreignObject
image
line
path
polygon
polyline
rect
svg
switch
text
textPath
tspan
and
use
it also includes a
symbol
element that
is
the
instance root
of a
use-element shadow tree
A renderable element may or may not be rendered
in a given document or point in time.
3.2.2. Rendered versus non-rendered elements
At any given time, every SVG element
(or
element instance
in a
use-element shadow tree
is either rendered or non-rendered.
Whether an element is currently rendered or not affects
not only its visual display but also interactivity
and geometric calculations.
An element is
not rendered
in any of these five situations:
never-rendered element
types
elements excluded because of
conditional processing attributes
or
switch
structures
elements with a computed style value of
none
for the
display
property
detached from the DOM tree
descendent elements of other non-rendered elements
Non-rendered elements:
have no visual effect on the graphic,
except when they are used in the rendering of another element
that references them.
do not contribute to the net geometry of
clipping paths
or
masks
when they are descendants of a
clipPath
or
mask
are not sensitive to
pointer events
cannot receive
focus
do not contribute to
bounding box
calculations
are not considered when performing
text layout
Non-rendered elements are not represented in the document accessibility tree.
Nonetheless, they remain part of the document model, and
participate in
style inheritance and cascade
3.2.3. Controlling visibility: the effect of the ‘
display
’ and ‘
visibility
properties
SVG uses two properties to toggle the visible display of
elements that are normally rendered:
display
and
visibility
Although they have a similar visible effect in static documents,
they are conceptually distinct.
See the CSS 2.1 specification for the definitions
of
display
and
visibility
CSS2
Setting
display
to
none
results in the element not being rendered.
When applied to
graphics elements
text content elements
and
container elements
that are normally rendered,
setting
display
to
none
results in the element (and all its descendents)
not becoming part of the
rendering tree
Note that
display
is not an inherited property.
Elements that have any other
display
value than
none
are rendered as normal.
The
display
property only applies to
renderable elements
Setting
display: none
on an element
that is
never directly rendered
or
not rendered
based on conditional processing
has no effect.
The
display
property affects the direct processing
of a given element, but it does not prevent it from
being referenced by other elements.
For example, setting
display: none
on a
path
element
will prevent that element from getting rendered directly onto the
canvas, but the
path
element can still be referenced by a
textPath
element and its geometry will be used
in text-on-a-path processing.
When applied to a
graphics element
or
use
element,
setting
visibility
to
hidden
or
collapse
results in the element not being painted.
It is, however, still part of the
rendering tree
It may be sensitive to pointer events
(depending on the value of
pointer-events
),
may receive focus (depending on the value of
tabindex
),
contributes to bounding box calculations and clipping paths,
and does affect text layout.
The
visibility
property only directly affects the rendering of
graphics elements
text content elements
, and the
element when it is a child of
text content element
Since
visibility
is an inherited property, however,
although it has no effect on a
use
element or
container element
itself,
its inherited value can affect descendant elements.
3.2.4. Re-used graphics
Graphical content defined in one part of the document
(or in another document)
may be used to render other elements.
There are two types of re-used graphics from a rendering perspective:
shadow DOM elements,
such as those generated by
use
elements
or by cross-references between paint servers;
content re-used as part of a graphical effect on another element,
including the child content of
markers
paint server elements
clipPath
, and
mask
Shadow DOM elements are rendered in the same way as normal elements,
as if the host element (e.g., the
use
element)
was a container and the shadow content was its descendents.
Style and geometry properties on the shadow DOM elements
are resolved independently from those on their
corresponding element
in the source document.
The
display
property has its normal effect on shadow elements,
except for special rules that apply to the
symbol
element.
For blending purposes, the
use
element forms a
non-isolated group
In contrast,
graphical effects elements generate a self-contained SVG fragment
which is rendered independently as a
stacking context
and an
isolated group
The canvas for this fragment is scaled

The graphical effect element's child content
is rendered and composited into this canvas.
The flattened canvas as a whole is treated as a vector image
when compositing and blending with other paint layers
The
display
property on any child content of a graphical effects element
has its normal effect when set to
none
excluding that subtree from being used in rendering.
However, the graphical effect is not altered
by a value of
display: none
on the graphical effect element or an ancestor.
3.3. The painters model
SVG uses a "painters model" of rendering.
Paint
is applied in successive operations to the output device such
that each operation paints onto some area of the output device,
possibly obscuring paint that has previously been laid down.

After each object or group is painted, it becomes part of the background
for the next painting operation.

SVG 2 supports advanced blending modes and compositing operations that
control how each painting operation interacts with the background.
The rules governing these painting operations are outlined in the
Compositing and Blending Specification
3.4. Rendering order
Elements in SVG are positioned in three dimensions. In addition to their
position on the x and y axis of the
SVG viewport
, SVG elements are also
positioned on the z axis. The position on the z-axis defines the order that
they are painted.
Along the z axis, elements are grouped into
stacking contexts
3.4.1. Establishing a stacking context in SVG
A new stacking context must be established at an SVG element for its descendants if:
it is the root element
the element is an
outermost svg element
, or a
foreignObject
image
marker
mask
pattern
symbol
or
use
element
the element is an inner
svg
element and the computed value of its
overflow
property is a value other than
visible
the element is subject to explicit clipping:
the
clip
property applies to the element and it has a
computed value other than
auto
the
clip-path
property applies to the element and it has a
computed value other than
none
the
opacity
property applies to the element and it has a
computed value other than
the
mask
property applies to the element and it has a computed
value other than
none
the
filter
property applies to the element and it has a
computed value other than
none
a property defined in another specification is
applied and that property is defined to establish a stacking context in SVG
Stacking contexts are conceptual tools used to describe the
order in which elements must be painted one on top of the other when the
document is rendered, and for determining which element is highest when
determining the target of a pointer event. Stacking contexts do
not affect the position of elements in the DOM tree, and their presence or
absence does not affect an element's position, size or orientation in the
canvas' X-Y plane - only the order in which it is painted.
Stacking contexts can contain further stacking contexts. A stacking context is
atomic from the point of view of its parent stacking context; elements in
ancestor stacking contexts may not come between any of its elements.
Each element belongs to one stacking context. Elements in a stacking context
must be stacked according to document order.
With the exception of the
foreignObject
element, the back to front
stacking order for a stacking context created by an SVG element is:
the background and borders of the element forming the stacking
context, if any
descendants, in tree order
Since the
foreignObject
element creates a "fixed position containing block" in
CSS terms, the normative rules for the stacking order of the stacking context
created by
foreignObject
elements are the rules in Appendix E of CSS 2.1.
3.5. How elements are rendered
Individual
graphics elements
are treated as if they are a
non-isolated group
the components (fill, stroke, etc) that make up a graphic element
(See
Painting shapes and text
) being
members of that group. See
How groups are rendered
3.6. How groups are rendered
Grouping elements, such as the
element (see
container elements
) create a
compositing group
Similarly, a
use
element creates a compositing group for its shadow content.
The
Compositing and Blending
specification normatively describes how to render
compositing groups
In SVG, effects may be applied to a group. For example, opacity, filters
or masking. These effects are applied to the rendered result of the group
immediately before any transforms on the group are applied, which are applied
immediately before the group is blended and composited with the
group backdrop
. Applying any such effects to a group makes that
group isolated.
Thus, rendering a
compositing group
follows the following steps:
If the group is isolated:
The
initial backdrop
is set to a new buffer initialised with
rgba(0,0,0,0)
The contents of the group that are
graphics elements
or
elements are rendered
in order
, onto the
initial backdrop
filters and other effects that modify the group canvas are applied
To provide for high quality rendering, filter
primitives and other bitmap effects must be applied in the
operating coordinate space
Group transforms are applied
The group canvas is blended and composited with the
group backdrop
else (the group is not isolated):
The
initial backdrop
is set to the
group backdrop
The contents of the group that are
graphics elements
or
elements are rendered
in order
, onto the
initial backdrop
. The group transforms are applied to each element
as they are rendered.
3.6.1. Object and group opacity: the
effect of the ‘
opacity
’ property
See the CSS Color Module Level 3 for the definition
of
opacity
. [
css-color-3
The
opacity
property specifies how opaque a given
graphical element or container element will be when it is
painted to the canvas. When applied to a container element,
this is known as
group opacity
, and when applied to
an individual rendering element, it is known as
object
opacity
. The principle for these two operations however
is the same.
There are several other opacity-related properties in SVG:
fill-opacity
, which specifies the opacity of a fill
operation;
stroke-opacity
, which specifies the opacity of a stroking
operation; and
stop-opacity
, which specifies the opacity of a gradient stop.
These four opacity properties are involved in intermediate rendering operations.
Object and group opacity however can be thought of as a post-processing operation.
Conceptually, the object or group to which
opacity
applies
is rendered into an RGBA offscreen image. The offscreen image as whole is then blended
into the canvas with the specified
opacity
value used uniformly
across the offscreen image.
Thus, the presence of
opacity
causes the group to be
isolated
The
opacity
property applies to the following SVG elements:
svg
symbol
marker
switch
use
and
graphics elements
The following example illustrates various usage of the
opacity
property on objects and groups.

Each group of red and green circles is first rendered
to an offscreen image before being blended with the background
blue rectangle as a whole, with the given
opacity
values.
In the example, the top row of circles have differing opacities,
ranging from 1.0 to 0.2. The bottom row illustrates five
elements,
each of which contains overlapping red and green circles, as follows:
The first group shows the opaque case for reference. The group has
opacity of 1, as do the circles.
The second group shows group opacity when the elements in the group are
opaque.
The third and fourth group show that opacity is not commutative. In the
third group (which has opacity of 1), a semi-transparent green circle is
drawn on top of a semi-transparent red circle, whereas in the fourth group a
semi-transparent red circle is drawn on top of a semi-transparent green
circle. Note that area where the two circles intersect display different
colors. The third group shows more green color in the intersection area,
whereas the fourth group shows more red color.
The fifth group shows the multiplicative effect of opacity settings.
Both the circles and the group itself have opacity settings of .5. The
result is that the portion of the red circle which does not overlap with the
green circle (i.e., the top/right of the red circle) will blend into the
blue rectangle with accumulative opacity of .25 (i.e., .5*.5), which, after
blending into the blue rectangle, results in a blended color which is 25%
red and 75% blue.
3.7. Types of graphics elements
SVG supports three fundamental types of
graphics elements
that can be rendered onto the canvas:
Shapes
, which represent some combination of straight line
and curves
Text, which represents some combination of character glyphs
Raster images, which represent an array of values that
specify the paint color and opacity (often termed alpha) at a
series of points on a rectangular grid. (SVG requires support
for specified raster image formats under
conformance requirements
.)
3.7.1. Painting shapes and text
Shapes and text can be
filled
(i.e., apply paint to the
interior of the shape) and
stroked
(i.e., apply paint
along the outline of the shape).
For certain types of shapes,
marker
symbols
(which themselves can consist of any combination of shapes,
text and images) can be drawn at positions along the
shape boundary. Each marker symbol
is painted as if its graphical content were expanded into the
SVG document tree just after the shape object which is using
the given marker symbol. The graphical contents of a marker
symbol are rendered using the same methods as graphics
elements. Marker symbols are not applicable to text.
The order in which fill, stroke and markers are painted is determined
by the
paint-order
property. The default is that
fill is painted first, then the stroke, and then the
marker symbols. The marker symbols are rendered in order along
the outline of the shape, from the start of the shape to the
end of the shape.
The fill and stroke operations are entirely independent;
for instance, each fill or stroke operation has its own opacity setting.
SVG supports numerous built-in types of paint which can
be used in fill and stroke operations. These are described in
Paint Servers
3.7.2. Painting raster images
When a raster image is rendered, the original samples are
"resampled" using standard algorithms to produce samples at the
positions required on the output device. Resampling
requirements are discussed under
conformance requirements
As in HTML [
HTML
, 10.4.2],
all animated images with the same absolute URL and the same image
data are expected to be rendered synchronised to the same timeline as a group,
with the timeline starting at the time of the least recent addition to the
group.
When a user agent is to restart the animation for an img element showing an
animated image, all animated images with the same absolute URL and the same
image data in that img element's node document are expected to restart their
animation from the beginning.
3.8. Filtering painted regions
SVG allows any painting operation to be filtered. (See
Filter Effects
.)
In this case the result must be as though the paint
operations had been applied to an intermediate canvas
initialized to transparent black, of a size determined by the
rules given in
Filter Effects
then
filtered by the processes defined in
Filter Effects
3.9. Clipping and masking
SVG supports the following clipping/masking features:
clipping paths, which either uses
any combination of
path
text
and
basic shapes
or basic shapes to serve as
the outline of a (in the absence of anti-aliasing) 1-bit
mask, where everything on the "inside" of the outline is
allowed to show through but everything on the outside is
masked out
masks, which are
container elements
which can contain
graphics elements
or other container elements which define a set of graphics
that is to be used as a semi-transparent mask for compositing
foreground objects into the current background.
Both, clipping and masking, are specified in the module CSS Masking
css-masking-1
].
3.10. Parent compositing
SVG document fragments can be semi-opaque.
In accordance with the
Compositing and Blending
specification,
the
svg
element always creates an
isolated
group.
When an SVG document is a top-level document,
meaning it is not embedded in another document,
the root
svg
element
is considered to be the
page group
and is composited with
a backdrop of white with 100% opacity.
In all other cases, the SVG document or document fragment is composited into the parent
document with opacity preserved.
3.11. The effect of the ‘
overflow
property
See the Cascading Style Sheets Level 2 Revision 1 (CSS 2.1)
Specification [
CSS2
] for the definition of
overflow
A summary of the behavior of the
overflow
property in SVG.
element
initial
ua stylesheet
auto
visible
hidden
scroll
document root svg
visible
n/a
visible | scroll
visible
hidden
scroll
other svg
visible
hidden
visible | scroll
visible
hidden
scroll
text
visible
hidden
visible
visible
hidden
hidden
pattern
visible
hidden
visible
visible
hidden
hidden
marker
visible
hidden
visible
visible
hidden
hidden
symbol
visible
hidden
visible
visible
hidden
hidden
image
visible
hidden
visible
visible
hidden
hidden
foreignObject
visible
hidden
visible | scroll
visible
hidden
scroll
The
overflow
property has the same parameter values and has the
same meaning
as defined in CSS 2.1
([
CSS2
], section 11.1.1);
however, the following additional points apply:
If the
overflow
property has a value of 'visible',
the property has no effect (i.e., a clipping rectangle is not created).
For those elements to which the
overflow
property can apply.
If the
overflow
property has the value
hidden
or
scroll
, a clip,
the exact size of the SVG viewport is applied.
When
scroll
is specified on an
svg
element and if the user agent uses a scrolling mechanism that
is visible on the screen (such as a scroll bar or a panner), that mechanism
should be displayed for the SVG viewport whether or not any of its content is clipped.
Within SVG content, the value
auto
implies
that all rendered content for child elements must be
visible
, either through a scrolling
mechanism, or by rendering with no clip.
For elements where the value of
scroll
results
in a scrolling mechanism being used by the user agent, then a value of
auto
may be treated as
scroll
. If the user agent has no scrolling
mechanism, the content would not be clipped, or the value 'scroll' is treated
as
hidden
, then the value
auto
must be treated as
visible
Although the initial value for
overflow
is auto. In the User Agent style sheet,
overflow is overridden for the
svg
element when it is not the root
element of a stand-alone document, the
pattern
element, and the
marker
element to be hidden by default.
Chapter 4: Basic Data Types and Interfaces
4.1. Definitions
initial value
The initial value of an attribute or property is the value used when
that attribute or property is not specified, or when it has an
invalid value
This value is to be used for the purposes of rendering, calculating
animation values
and when accessing the attribute or property via DOM interfaces.
invalid value
An invalid value specified for a
property
, either in a style sheet
or a
presentation attribute
, is one that is either not allowed according
to the grammar defining the property's values, or is allowed by the grammar but
subsequently disallowed in prose. A CSS declaration with an invalid value is
ignored
4.2. Attribute syntax
In this specification, attributes are defined with an attribute definition
table, which looks like this:
Name
Value
Initial value
Animatable
exampleattr

| none
none
yes
In the Value column is a description of the attribute's syntax. There are
six methods for describing an attribute's syntax:
Using the
CSS Value
Definition Syntax
css-values
].
This is the notation used to define the syntax for most attributes in this
specification and is the default.
By reference to an
EBNF symbol
defined
in this or another specification [
xml
].
For external definitions, this is indicated by
[EBNF]
appearing in the Value column.
By reference to an
ABNF symbol
defined
in another specification [
rfc5234
]. This is
indicated by
[ABNF]
appearing in the Value
column.
As a URL as defined by the
URL
Standard
URL
]. This is indicated by
[URL]
appearing in the Value column.
As a type as defined by the
HTML
Standard
HTML
]. This is indicated by
[HTML]
appearing in the Value column.
In prose, below the attribute definition table. This is indicated by the
text "(see below)" appearing in the Value column.
SVG 2 Requirement:
Consider relaxing case sensitivity of presentation attribute values.
Resolution:
We will make property values case insensitivity.
Purpose:
To align presentation attribute syntax parsing with parsing of the corresponding CSS property.
Owner:
Cameron (
ACTION-3276
Status:
Done
When a
presentation attribute
defined using the CSS Value Definition Syntax is parsed, this is done as
follows:
Let
value
be the value of the attribute.
Let
grammar
be the grammar given in the attribute definition
table's Value column.
Replace all instances of

in
grammar
with


].
Replace all instances of

in
grammar
with


].
Replace all instances of

in
grammar
with


].
Return the result of
parsing
value
with
grammar
The insertion of the

symbols allows for
unitless length and angles to be used in presentation attribute while
disallowing them in corresponding property values.
Note that all
presentation attributes
, since they are
defined by reference to their corresponding CSS properties, are defined using
the CSS Value Definition Syntax.
When any other attribute defined using the CSS Value
Definition Syntax is parsed, this is done by
parsing the
attribute's value according to the grammar given in attribute definition
table
Note that this allows CSS comments and escapes to be used
in such attributes. For example, a value of
'10\px/**/'
would successfully parse as
'10px'
in
the
‘x’
presentation attribute of the
rect
element.
When an attribute defined as a URL is parsed, this is
done by invoking the
URL parser
with
the attribute's value as
input
and the document's URL as
base
URL
].
The Initial value column gives the
initial value
for the attribute.
When an attribute fails to parse according to the specified CSS Value Definition Syntax,
ABNF or EBNF grammar, or if parsing according to the URL Standard
or by the prose describing how to parse the attribute indicates failure,
the attribute is assumed to have been specified as the given
initial value
The initial value of a
presentation attribute
is its
corresponding property's initial value. Since the use of an
invalid value
in a
presentation attribute
will be treated as if the initial value
was specified, this value can override values that come from lower priority
style sheet rules, such as those from the user agent style sheet.
For example, although the user agent style sheet sets the value of the
overflow
property to
hidden
for
svg
elements, specifying an invalid presentation attribute such
as
overflow="invalid"
will result
in a rule setting
overflow
to
visible
overriding the user agent style sheet value.
The Animatable column indicates whether the attribute can be animated using
animation elements
as defined in the
SVG Animation
module.
4.2.1. Real number precision
Unless stated otherwise, numeric values in SVG attributes and in
properties that are defined to have an effect on SVG elements must
support at least all finite single-precision values supported by the host
architecture.
It is recommended that higher precision floating point
storage and computation be performed on operations such as
coordinate system transformations to provide the best
possible precision and to prevent round-off errors.
conforming SVG viewers
are required to perform numerical computation in accordance with their
conformance class, as described in
Conformance Criteria
4.2.2. Clamping values which are restricted to a particular range
Some numeric attribute and property values have restricted ranges.
Other values will be restricted by the capabilities of the device.
If not otherwise specified,
the user agent shall defer any out-of-range error checking until
as late as possible in the rendering process.
This is particularly important for device limitations,
as compound operations
might produce intermediate values which are out-of-range but
final values which are within range.
4.3. SVG DOM overview
Conforming
SVG viewers
or
SVG interpreters
that support
script execution
must implement SVG DOM interfaces as defined throughout this specification,
with the specific requirements and dependencies listed in this section.
SVG 2 Requirement:
Improve the DOM.
Resolution:
We will generally improve the SVG DOM for SVG 2.
Purpose:
Help authors use the SVG DOM by making it less Java-oriented.
Owner:
Cameron (
ACTION-3273
Note:
See
SVG 2 DOM
Wiki page.
SVG 2 Requirement:
Improve the SVG path DOM APIs.
Resolution:
We will improve the SVG path DOM APIs in SVG 2.
Purpose:
Clean up SVGPathSegList interface, and possibly share an API with Canvas.
Owner:
Cameron (no action)
4.3.1. Dependencies for SVG DOM support
The SVG DOM is defined in terms of
Web IDL
interfaces. All IDL fragments in this specification must be interpreted as
required for
conforming IDL fragments
as described in the Web IDL specification. [
WebIDL
The SVG DOM builds upon a number of DOM specifications. In particular:
The SVG DOM requires full support for the DOM,
as defined by the most recent
Review Draft
of the DOM living standard at the time this specification was published,
except for any features that have been removed or deprecated since.
SVG software with DOM support should implement
the
latest DOM standard
wherever possible
DOM
The SVG DOM requires support for relevant aspects of
UI Events
and
Clipboard API and events
([
uievents
], [
clipboard-apis
]).
(For the specific features that are required, see
Relationship with UI Events
.)
The SVG DOM requires, at a minimum, complete
support for all interfaces from
DOM Level 2 Style
([
dom-level-2-style
])
that have not been dropped in the
CSS Object Model (CSSOM)
specification.
SVG software should implement the latest version of
CSS Object Model (CSSOM)
wherever possible
([
cssom-1
])
The SVG DOM requires complete support for
Geometry Interfaces Module Level 1
([
geometry-1
]).
4.3.2. Naming conventions
The SVG DOM follows similar naming conventions to HTML and DOM standards
([
HTML
], [
DOM
]).
All names are defined as one or more English words
concatenated together to form a single string. Property or
method names start with the initial keyword in lowercase, and
each subsequent word starts with a capital letter. For example,
a property that returns document meta information such as the
date the file was created might be named "fileDateCreated".
Interface names defined in this specification nearly all start with "SVG".
Interfaces that represent the DOM
Element
object
for an SVG-namespaced element follow the format
SVG
ElementName
Element
, where
ElementName
is the element's tag name with the initial letter capitalized.
So
SVGRadialGradientElement
is the interface for an
radialGradient
element.
An exception to this casing convention is
SVGSVGElement
in which the entire tag name is capitalized.
4.3.3. Elements in the SVG DOM
Any SVG software that is required to support the SVG DOM
must enhance the DOM elements created for
SVG document fragments
as follows:
Every
Element
object that corresponds to a supported SVG element (that is,
an element with namespace URI "http://www.w3.org/2000/svg" and a
local name that is one of the elements defined in this specification
or another specification implemented by the software)
must also implement the DOM interface identified in the element definition.
Elements in the SVG namespace whose local name does not match an element
defined in any specification supported by the software
must nonetheless implement the
SVGElement
interface.
In
The
‘rect’
element
the
SVGRectElement
interface is identified. This means that every
Element
object whose namespace URI is "http://www.w3.org/2000/svg"
and whose local name is "rect" must also implement
SVGRectElement
4.3.4. Reflecting content attributes in the DOM
Many SVG DOM properties (IDL attributes)
reflect
a content attribute or property
on the corresponding element,
meaning that content and IDL attributes represent the same underlying data.
For example,
the
SVGAnimatedLength
ry
in an
SVGRectElement
reflects the
ry
presentation attribute on the associated
rect
element.
The way this reflection is done depends on the type of the IDL attribute:
If the type of the reflecting IDL attribute is a
primitive type
(such as
long
, as used by
tabIndex
on
SVGElement
) or
DOMString
(as used by
title
on
SVGStyleElement
),
then the rules for
reflecting
content attributes in IDL attributes
in HTML are used.
If the type of the reflecting IDL attribute is an
SVGAnimatedBoolean
SVGAnimatedString
SVGAnimatedEnumeration
SVGAnimatedNumber
SVGAnimatedNumberList
SVGAnimatedLength
SVGAnimatedLengthList
SVGAnimatedAngle
SVGAnimatedRect
or
SVGAnimatedPreserveAspectRatio
then the rules in the corresponding
section defining the reflecting interface are used.
At a high level, the object's
baseVal
is used to reflect the value of the content attribute.
For objects that reflect a CSS property, the
baseVal
is used
to reflect the presentation attribute.
This relationship is live, and values must be synchronized
(following the rules in
Synchronizing reflected values
when either the attribute or its reflected property is modified.
If the attribute hasn't been specified explicitly in the document markup,
the reflected object is nonetheless initialized upon access,
to the attribute's initial value.
If the attribute's initial value is
(none)
the object is initialized as defined in
Reflecting an empty initial value
This newly constructed object does not generate an attribute on the element until
it is modified for the first time. Modifications made to the corresponding
attribute are immediately reflected in the object.
If
lineElement.x1.baseVal
is accessed
(where
lineElement
is an instance of
SVGLineElement
and the
x1
attribute was not specified in the document, the
returned
SVGLength
object would represent the value
0 user units
because the initial value for the attribute is
4.3.5. Synchronizing reflected values
Whenever a reflected content attribute's base value changes,
then the reflecting object must be
synchronized
immediately after the value changed, by running the following steps:
If the reflecting object is a
list interface
object,
then run the steps for
synchronizing
a list interface object
Otherwise, update the object's value to be the base value of the reflected
content attribute (using the attribute's
initial value
if it is not
present or invalid).
This will, for example, update the
value
of an
SVGLength
object.
When a
reflected
content attribute is to be
reserialized
, optionally using a
specific value, the following steps must be performed:
Let
value
be the specific value given, or
the value of the content attribute's reflecting IDL attribute
if a specific value was not provided.
Depending on
value
's type:
SVGAnimatedBoolean
SVGAnimatedNumber
SVGAnimatedLength
SVGAnimatedAngle
SVGAnimatedRect
SVGAnimatedString
SVGAnimatedNumberList
SVGAnimatedLengthList
SVGAnimatedTransformList
Reserialize
the content attribute using
value
's baseVal member.
SVGAnimatedEnumeration
Let
number
be the value of
value
's
baseVal member.
Let
keyword
be the content attribute's keyword
value corresponding to
number
, or the empty string
if
number
is 0.
This means that if the enumeration value is
somehow set to the "unknown" value, the content attribute will be
set to the empty string.
However, this unknown value can never be set directly on the
SVGAnimatedEnumeration
object;
it represents an unknown attribute value set in the markup.
Set the content attribute to
keyword
boolean
Set the content attribute to "true" if
value
is true,
and "false" otherwise.
float
double
Set the content attribute to an implementation specific string
that, if parsed as a

using CSS syntax,
would return the number value closest to
value
, given
the implementation's supported
real number precision
SVGLength
Set the content attribute to the value that would be returned
from getting
value
's
valueAsString
member.
SVGAngle
Set the content attribute to the value that would be returned
from getting
value
's
valueAsString
member.
DOMRect
Let
components
be a list of four values, being the values of the
width
and
height
members of
value
Let
serialized components
be a list of four strings,
where each is an implementation specific string that, if parsed
as a

using CSS syntax, would return the number
value closest to the corresponding value in
components
, given
the implementation's supported
real number precision
Set the content attribute to a string consisting of the strings in
serialized components
joined and separated by single
U+0020 SPACE characters.
DOMString
Set the content attribute to
value
SVGNumberList
SVGLengthList
SVGPointList
SVGTransformList
SVGStringList
Let
elements
be the list of values in
value
The values will be
SVGNumber
SVGLength
DOMPoint
or
SVGTransform
objects, or
DOMString
values,
depending on
value
's type.
Let
serialized elements
be a list of strings, where each
string is formed based on the corresponding value in
elements
and its type:
an
SVGNumber
object
The string is an implementation specific string that, if parsed
as a

using CSS syntax, would return the number
value closest to the
SVGNumber
object's
value
member, given
the implementation's supported
real number precision
an
SVGLength
object
The string is the value that would be returned
from getting the value's
valueAsString
member.
DOMPoint
object
The string value is computed as follows:
Let
string
be an empty string.
Let
and
be the values of the
DOMPoint
object's x and y coordinates, respectively.
Append to
string
an implementation specific string
that, if parsed as

using CSS syntax, would return the number
value closest to
, given
the implementation's supported
real number precision
Append a single U+002C COMMA character to
string
Append to
string
an implementation specific string
that, if parsed as

using CSS syntax, would return the number
value closest to
, given
the implementation's supported
real number precision
The string is
string
SVGTransform
object
The string is the
serialization
of the
SVGTransform
object's
matrix object
DOMString
The string is the
DOMString
's value itself.
Set the content attribute to a string consisting of the strings in
serialized elements
joined and separated by single
U+0020 SPACE characters.
4.3.6. Reflecting an empty initial value
When initializing an SVG DOM attribute that
reflects
a null or empty initial value,
then the property must be initialized according to its data type,
as defined in this section.
This occurs only if there is no explicit value for the reflected content attribute,
and the initial value in the attribute's definition table is
(none)
If an interface is not listed below that means
that the object initialization shall be done using the values for the
objects that the interface contains, e.g.,
an
SVGAnimatedString
consists of two
DOMString
members,
while a
DOMRect
consists of many
double
s.
DOMString
Initialized as the empty string (
""
).
float
long
short
Any other
numeric type
defined in WebIDL
Initialized as
boolean
Initialized as
false
SVGLength
Initialized as
0 user units
SVG_LENGTHTYPE_NUMBER
).
SVGLengthList
SVGNumberList
SVGPointList
SVGStringList
SVGTransformList
Initialized as the empty list.
SVGAngle
Initialized as
0 in unspecified units
SVG_ANGLETYPE_UNSPECIFIED
).
SVGPreserveAspectRatio
Initialized as
'xMidYMid meet'
If
textElement.dx.baseVal
is accessed
(where
textElement
is an instance of
SVGTextElement
and the
dx
attribute was not specified in the document, the
returned
SVGLengthList
object would be empty.
4.3.7. Invalid values
If a script sets a
reflected
DOM attribute
to an
invalid value
for the content attribute (e.g.,
a negative number for an attribute that requires a non-negative
number), unless
this specification indicates otherwise, no exception shall be
raised on setting, but the given document fragment shall become
technically
in error
as described in
Error processing
DOM attributes that reflect enumerated values using integer constants are an exception:
these throw a
TypeError
when set to an out-of-range integer,
or to the constant (0) that represents an unknown attribute value.
This is consistent with the
behavior of the WebIDL enumeration type
WebIDL
].
4.4. DOM interfaces for SVG elements
4.4.1. Interface SVGElement
All of the SVG DOM interfaces that correspond directly to elements in the
SVG language (such as the
SVGPathElement
interface for the
path
element) derive from the
SVGElement
interface.
The CSSOM specification
augments
SVGElement with a style IDL attribute
, so that the
style
attribute can be accessed in the same way as on HTML elements.
Exposed
=Window]
interface
SVGElement
Element

SameObject
] readonly attribute
SVGAnimatedString
className

readonly attribute
SVGSVGElement
ownerSVGElement
readonly attribute
SVGElement
viewportElement
};
SVGElement
includes
GlobalEventHandlers
SVGElement
includes
SVGElementInstance
SVGElement
includes
HTMLOrSVGElement
The
className
IDL attribute
reflects
the
class
attribute.
This attribute is deprecated and may be removed in a
future version of this specification. Authors are advised to use
Element.classList instead.
The
className
attribute on
SVGElement
overrides the correspond attribute on
Element
, following the WebIDL rules for
inheritance
The
ownerSVGElement
IDL attribute
represents the nearest ancestor
svg
element. On getting
ownerSVGElement
the nearest ancestor
svg
element is returned; if the current
element is the
outermost svg element
, then null is returned.
The
viewportElement
IDL attribute
represents the element that provides the SVG viewport for the current element. On getting
viewport
the nearest ancestor element that establishes an SVG viewport is returned; if the current
element is the
outermost svg element
, then null is returned.
4.4.2. Interface SVGGraphicsElement
SVG 2 Requirement:
Detect if a mouse event is on the fill or stroke of a shape.
Resolution:
SVG 2 will make it easier to detect if an mouse event is on the stroke or fill of an element.
Purpose:
To allow authors to discriminate between pointer events on the fill and stroke of an element without having to duplicate the element
Owner:
Cameron (
ACTION-3279
Status:
Done.
The
SVGGraphicsElement
interface represents SVG elements whose primary purpose
is to directly render graphics into a group.
dictionary
SVGBoundingBoxOptions
boolean fill = true;
boolean stroke = false;
boolean markers = false;
boolean clipped = false;
};

[Exposed=Window]
interface
SVGGraphicsElement
SVGElement
SameObject
] readonly attribute
SVGAnimatedTransformList
transform
DOMRect
getBBox
(optional
SVGBoundingBoxOptions
options = {});
DOMMatrix
getCTM
();
DOMMatrix
getScreenCTM
();
};
SVGGraphicsElement
includes
SVGTests
The
transform
IDL attribute
reflects
the computed value of the
transform
property and its
corresponding
‘transform’
presentation attribute.
The
getBBox
method is used
to compute the bounding box of the current element. When the getBBox(
options
method is called, the
bounding box algorithm
is invoked for the current element,
with
fill
stroke
markers
and
clipped
members of the
options
dictionary argument
used to control which parts of the element are included in the bounding box,
using the element's user coordinate system as the coordinate system to return the
bounding box in. A newly created
DOMRect
object that defines the
computed bounding box is returned. If
getBBox
gets called on a
non-rendered element
, and the UA is not able to compute the geometry of the element, then
throw an
InvalidStateError
The
getCTM
method is used to
get the matrix that transforms the current element's coordinate system to
its SVG viewport's coordinate system. When getCTM() is called, the following
steps are run:
If the current element is not in the document, then return null.
If the current element is a
non-rendered element
, and the UA
is not able to resolve the style of the element, then return null.
Let
ctm
be a matrix determined based on what the
current element is:
the current element is the
outermost svg element
ctm
is a matrix that transforms the coordinate
space of the
svg
(including its
transform
property)
to the coordinate space of the document's viewport. The matrix includes the
transforms produced by the
viewBox
and
preserveAspectRatio
attributes, the
transform
property, and any transform
due to
currentScale
and
currentTranslate
properties on the
SVGSVGElement
any other element
ctm
is a matrix that transforms the coordinate
space of the current element (including its
transform
property) to the coordinate space of its closest ancestor
viewport-establishing element (also including its
transform
property).
Return a newly created,
detached
DOMMatrix
object that represents the same matrix as
ctm
The
getScreenCTM
method
is used to get the matrix that transforms the current element's coordinate
system to the coordinate system of the SVG viewport for the SVG document fragment.
When getScreenCTM() is called, the following steps are run:
If the current element is not in the document, then return null.
If the current element is a
non-rendered element
, and the UA
is not able to resolve the style of the element, then return null.
Let
ctm
be a matrix that transforms the coordinate
space of the current element (including its
transform
property)
to the coordinate space of the document's viewport.
This will include:
all of the transforms from the current element up to the
outermost svg element
any transforms due to
viewBox
preserveAspectRatio
the
transform
property and any transform
due to
currentScale
and
currentTranslate
properties on the
SVGSVGElement
for the
outermost svg element
any transforms from the SVG viewport's coordinate space
to the document's viewport, i.e. taking into account the positions of
all of the CSS boxes from the
outermost svg element
's box
to the initial containing block when the SVG document fragment
is inline in an HTML document
Return a newly created,
detached
DOMMatrix
object that represents the same matrix as
ctm
This method would have been more aptly named as
getClientCTM
but the name
getScreenCTM
is kept for historical reasons.
4.4.3. Interface SVGGeometryElement
Interface
SVGGeometryElement
represents SVG elements whose rendering
is defined by geometry with an
equivalent path
and which can be filled and stroked.
This includes paths and the basic shapes.
Exposed
=Window]
interface
SVGGeometryElement
SVGGraphicsElement
SameObject
] readonly attribute
SVGAnimatedNumber
pathLength

boolean
isPointInFill
(optional
DOMPointInit
point = {});
boolean
isPointInStroke
(optional
DOMPointInit
point = {});
float
getTotalLength
();
DOMPoint
getPointAtLength
(float distance);
};
The
isPointInFill
method,
when invoked, must return true if the point given by
point
passed to the method,
in the coordinate space of an element, is inside the intended path as determined by the winding
rule indicated by the
fill-rule
property of an element; and must return false otherwise.
Open subpaths must be implicitly closed when computing the area inside the path, without affecting
the actual subpaths. Points on the path itself must be considered to be inside the path.
The returned value is independent of any visual CSS property but
fill-rule
If either of the
or
properties on
point
are infinite or NaN,
then the method must return false. If current element is a
non-rendered element
, and the UA is not able to compute the geometry of the element, then
throw an
InvalidStateError
isPointInFill
takes the winding
rule indicated by the
fill-rule
property of an element even if the element is a child
of a
clipPath
element.
isPointInFill
is aligned
with the
isPointInPath
method on the
CanvasDrawPath
mixin as much as the SVG context
allows it to be.
The
isPointInStroke
method,
when invoked, must return true if the point given by
point
passed to the method,
in the coordinate space of an element, is in or on the outline path of an applied stroke on
an element; and must return false otherwise.
The outline path must take the stroke properties
stroke-width
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-dasharray
stroke-dashoffset
and
vector-effect
of an element into account. See sections
Computing the shape of the stroke
and
Vector effects
for details.
The returned value is independent of any visual CSS property but the listed stroke properties.
If either of the
or
properties on
point
are infinite or NaN,
then the method must return false. If current element is a
non-rendered element
, and the UA is not able to compute the geometry of the element, then
throw an
InvalidStateError
isPointInStroke
is aligned
with the
isPointInStroke
method on the
CanvasDrawPath
mixin as much as the SVG context
allows it to be.
The
pathLength
IDL attribute
reflects
the
pathLength
content attribute.
The
getTotalLength
method
is used to compute the length of the path. When getTotalLength()
is called, the user agent's computed value for the total length of the path,
in user units, is returned. If current element is a
non-rendered element
, and the UA is not able to compute the total length of the path, then
throw an
InvalidStateError
The user agent's computed path length does not take the
pathLength
attribute into account.
The
getPointAtLength
method
is used to return the point at a given distance along the path. When
getPointAtLength(
distance
) is called, the following steps are run:
If current element is a
non-rendered element
, and the UA is not able to
compute the total length of the path, then throw an
InvalidStateError
Let
length
be the user agent's computed value for the total
length of the path, in user units.
As with
getTotalLength
this does not take into account the
pathLength
attribute.
Clamp
distance
to [0,
length
].
Let (
) be the point on the path at distance
distance
Return a newly created,
detached
DOMPoint
object representing the point
).
4.5. DOM interfaces for basic data types
4.5.1. Interface SVGNumber
The
SVGNumber
interface is used primarily to represent a

value that is a part of an
SVGNumberList
. Individual
SVGNumber
objects can also be created by script.
An
SVGNumber
object can be designated as
read only
which means that attempts to modify the object will result in an exception
being thrown, as described below.
SVGNumber
objects reflected through the animVal IDL attribute are always
read only
An
SVGNumber
object can be
associated
with a particular element. The associated element is used to
determine which element's content attribute to update if the object
reflects
an attribute. Unless otherwise described, an
SVGNumber
object is not
associated with any element.
Every
SVGNumber
object operates in one of two
modes. It can:
reflect an element of the base value
of a
reflected
animatable
attribute (being exposed through the methods on the
baseVal
member of
an
SVGAnimatedNumberList
),
be detached
, which is the case for
SVGNumber
objects created
with
createSVGNumber
An
SVGNumber
object maintains an internal number value,
which is called its
value
Exposed
=Window]
interface
SVGNumber
attribute float
value
};
The
value
IDL attribute
represents the number. On getting
value
the
SVGNumber
's
value
is returned.
On setting
value
, the following
steps are run:
If the
SVGNumber
is
read only
, then
throw
NoModificationAllowedError
Set the
SVGNumber
's
value
to the
value being assigned to the
value
member.
If the
SVGNumber
reflects an element of the
base value
of a
reflected
attribute, then
reserialize
the reflected attribute.
4.5.2. Interface SVGLength
The
SVGLength
interface is used to represent a value that
can be a


or

value.
An
SVGLength
object can be designated as
read only
which means that attempts to modify the object will result in an exception
being thrown, as described below.
SVGLength
objects reflected through the animVal IDL attribute are always
read only
An
SVGLength
object can be
associated
with a particular element, as well as being designated with a
directionality
horizontal, vertical or unspecified. The associated element and the directionality of the
length are used to resolve percentage values to user units and is also used to
determine which element's content attribute to update if the object
reflects
an attribute. Unless otherwise
described, an
SVGLength
object is not associated with any element and
has unspecified directionality.
Every
SVGLength
object operates in one of
four modes. It can:
reflect the base value
of a
reflected
animatable attribute
(being exposed through the
baseVal
member of an
SVGAnimatedLength
),
reflect a presentation attribute value
(such as by
SVGRectElement.width.baseVal
),
reflect an element of the base value
of a
reflected
animatable
attribute (being exposed through the methods on the
baseVal
member of
an
SVGAnimatedLengthList
), or
be detached
, which is the case for
SVGLength
objects created
with
createSVGLength
An
SVGLength
object maintains an internal

or

or

value, which is called its
value
Exposed
=Window]
interface
SVGLength

// Length Unit Types
const unsigned short
SVG_LENGTHTYPE_UNKNOWN
= 0;
const unsigned short
SVG_LENGTHTYPE_NUMBER
= 1;
const unsigned short
SVG_LENGTHTYPE_PERCENTAGE
= 2;
const unsigned short
SVG_LENGTHTYPE_EMS
= 3;
const unsigned short
SVG_LENGTHTYPE_EXS
= 4;
const unsigned short
SVG_LENGTHTYPE_PX
= 5;
const unsigned short
SVG_LENGTHTYPE_CM
= 6;
const unsigned short
SVG_LENGTHTYPE_MM
= 7;
const unsigned short
SVG_LENGTHTYPE_IN
= 8;
const unsigned short
SVG_LENGTHTYPE_PT
= 9;
const unsigned short
SVG_LENGTHTYPE_PC
= 10;

readonly attribute unsigned short
unitType
attribute float
value
attribute float
valueInSpecifiedUnits
attribute DOMString
valueAsString

undefined
newValueSpecifiedUnits
(unsigned short unitType, float valueInSpecifiedUnits);
undefined
convertToSpecifiedUnits
(unsigned short unitType);
};
The numeric length unit type constants defined on
SVGLength
are used
to represent the type of an
SVGLength
's
value
Their meanings are as follows:
Constant
Meaning
SVG_LENGTHTYPE_NUMBER
A unitless

interpreted as a value in
px
SVG_LENGTHTYPE_PERCENTAGE

SVG_LENGTHTYPE_EMS

with an
em
unit.
SVG_LENGTHTYPE_EXS

with an
ex
unit.
SVG_LENGTHTYPE_PX

with a
px
unit.
SVG_LENGTHTYPE_CM

with a
cm
unit.
SVG_LENGTHTYPE_MM

with a
mm
unit.
SVG_LENGTHTYPE_IN

with an
in
unit.
SVG_LENGTHTYPE_PT

with a
pt
unit.
SVG_LENGTHTYPE_PC

with a
pc
unit.
SVG_LENGTHTYPE_UNKNOWN
Some other type of value.
The use of numeric length unit type constants is an anti-pattern and
new constant values will not be introduced for any other units or length types supported by
SVGLength
. If other types of lengths are supported and used, the
SVGLength
uses the
SVG_LENGTHTYPE_UNKNOWN
unit type. See below for details on how the other properties of an
SVGLength
operate with these types of lengths.
The
unitType
IDL attribute represents
the type of value that the
SVGLength
's
value
is.
On getting
unitType
, the following steps
are run:
If the
SVGLength
's
value
is a unitless

, a

, or a

with an
em
ex
px
cm
mm
in
pt
or
pc
unit, then return the corresponding constant
value from the length unit type table above.
Otherwise, return
SVG_LENGTHTYPE_UNKNOWN
For example, for a

with a
ch
unit or one that has a non-scalar value such as
calc()
SVG_LENGTHTYPE_UNKNOWN
would be returned.
The
value
IDL attribute represents
the
SVGLength
's
value
in user units.
On getting
value
, the following steps
are run:
Let
value
be the
SVGLength
's
value
If
value
is a

, return that number.
Let
viewport size
be a basis to resolve percentages against, based on the
SVGLength
's
associated element
and
directionality
has no
associated element
size
is 100
has an
associated element
and horizontal
directionality
size
is the width of the
associated element
's SVG viewport
has an
associated element
and vertical
directionality
size
is the height of the
associated element
's SVG viewport
has an
associated element
and unspecified
directionality
size
is the length of the
associated element
's SVG viewport
diagonal (see
Units
Let
font size
be a basis to resolve font size values against,
based on the
SVGLength
's
associated element
has no
associated element
font size
is the absolute length of the initial value of the
font-size
property
has an
associated element
size
is the computed value of the
associated element
's
font-size
property
Return the result of converting
value
to an absolute length,
using
viewport size
and
font size
as percentage and font size
bases. If the conversion is not possible due to the lack of an
associated element
, return 0.
On setting
value
, the following steps
are run:
If the
SVGLength
object is
read only
, then
throw
NoModificationAllowedError
Let
value
be the value being assigned to
value
Set the
SVGLength
's
value
to a

whose value is
value
If the
SVGLength
reflects the base value
of a
reflected
attribute,
reflects a presentation attribute
, or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
valueInSpecifiedUnits
IDL attribute represents
the numeric factor of the
SVGLength
's
value
On getting
valueInSpecifiedUnits
, the following steps
are run:
Let
value
be the
SVGLength
's
value
If
value
is a

, return that number.
Otherwise, if
value
is a

or any scalar

value, return the numeric factor before its unit.
Otherwise, return 0.
Thus
valueInSpecifiedUnits
would return 12 for both
'12%'
and
12em
, but
0 would be returned for non-scalar values like
calc(12px + 5%)
On setting
valueInSpecifiedUnits
, the following steps
are run:
If the
SVGLength
object is
read only
, then
throw
NoModificationAllowedError
Let
value
be the value being assigned to
valueInSpecifiedUnits
If the
SVGLength
's
value
is a

, then update its value to
value
Otherwise, if the
SVGLength
's
value
is a

or a scalar-valued

then update its numeric factor to
value
Otherwise, the
SVGLength
's
value
is of some other type. Set it to a

whose value is
value
If the
SVGLength
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
valueAsString
IDL attribute represents
the
SVGLength
's
value
as a string.
On getting
valueAsString
, the following steps
are run:
Let
value
be the
SVGLength
's
value
Let
string
be an empty string.
If
value
is a


or scalar

value, then:
Let
factor
be
value
's numeric factor,
if it is a

or

or
value
itself it is a

Append to
string
an implementation
specific string that, if parsed as a

using CSS syntax,
would return the number value closest to
factor
, given the
implementation's supported
real number precision
If
value
is a

then append to
string
a single U+0025 PERCENT SIGN character.
Otherwise, if
value
is a

then append to
string
the canonical spelling of
value
's unit.
Return
string
Otherwise, return an implementation specific string that,
if parsed as a

, would return the closest
length value to
value
, given the
implementation's supported
real number precision
On setting
valueAsString
, the following steps
are run:
If the
SVGLength
object is
read only
, then
throw
NoModificationAllowedError
Let
value
be the value being assigned to
valueAsString
Parse
value
using the CSS syntax



].
If parsing failed, then
throw
SyntaxError
Otherwise, parsing succeeded. Set
SVGLength
's
value
to the parsed value.
If the
SVGLength
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
newValueSpecifiedUnits
method is used to set the
SVGLength
's value in a typed manner. When
newValueSpecifiedUnits(unitType, valueInSpecifiedUnits) is called, the following
steps are run:
If the
SVGLength
object is
read only
, then
throw
NoModificationAllowedError
If
unitType
is
SVG_LENGTHTYPE_UNKNOWN
or is a value that does not appear in the length unit type table above,
then
throw
NotSupportedError
Set
SVGLength
's
value
depending
on the value of
unitType
SVG_LENGTHTYPE_NUMBER

whose value is
valueInSpecifiedUnits
SVG_LENGTHTYPE_PERCENTAGE

whose numeric factor is
valueInSpecifiedUnits
anything else

whose numeric factor is
valueInSpecifiedUnits
and whose unit is as indicated by the length unit type table above
If the
SVGLength
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
convertToSpecifiedUnits
method is used to convert the
SVGLength
's value to a specific type.
When convertToSpecifiedUnits(unitType) is called, the following steps are run:
If the
SVGLength
object is
read only
, then
throw
NoModificationAllowedError
If
unitType
is
SVG_LENGTHTYPE_UNKNOWN
or is a value that does not appear in the length unit type table above,
then
throw
NotSupportedError
Let
absolute
be the value that would be returned from the
value
member.
If
unitType
is
SVG_LENGTHTYPE_NUMBER
, then:
Set the
SVGLength
's
value
to a

whose value is
absolute
Otherwise, if
unitType
is
SVG_LENGTHTYPE_PERCENTAGE
, then:
Let
viewport size
be a basis to resolve percentages against, based on the
SVGLength
's
associated element
and
directionality
has no
associated element
size
is 100
has an
associated element
and horizontal
directionality
size
is the width of the
associated element
's SVG viewport
has an
associated element
and vertical
directionality
size
is the height of the
associated element
's SVG viewport
has an
associated element
and unspecified
directionality
size
is the length of the
associated element
's SVG viewport
diagonal (see
Units
Set the
SVGLength
's
value
to the result of
converting
absolute
to a

, using
viewport size
as the percentage basis.
Otherwise, if
unitType
is
SVG_LENGTHTYPE_EMS
or
SVG_LENGTHTYPE_EXS
, then:
Let
font size
be a basis to resolve font size values against,
based on the
SVGLength
's
associated element
has no
associated element
font size
is the absolute length of the initial value of the
font-size
property
has an
associated element
size
is the computed value of the
associated element
's
font-size
property
Set the
SVGLength
's
value
to the result of
converting
absolute
to a

with an
em
or
ex
unit (depending on
unitType
),
using
font size
as the
font-size
basis.
Otherwise:
Set the
SVGLength
's
value
to the result of
converting
absolute
to a

with the unit
found by looking up
unitType
in the length unit type table above.
If the
SVGLength
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
4.5.3. Interface SVGAngle
The
SVGAngle
interface is used to represent a value that
can be an

or

value.
An
SVGAngle
object can be designated as
read only
which means that attempts to modify the object will result in an exception
being thrown, as described below. An
SVGAngle
reflected through the
animVal attribute is always
read only
An
SVGAngle
object can be
associated
with a particular element. The associated element is used to
determine which element's content attribute to update if the object
reflects
an attribute. Unless otherwise described, an
SVGAngle
object is not
associated with any element.
Every
SVGAngle
object operates in one of
two modes. It can:
reflect the base value
of a
reflected
animatable attribute
(being exposed through the
baseVal
member of an
SVGAnimatedAngle
),
be detached
, which is the case for
SVGAngle
objects created
with
createSVGAngle
An
SVGAngle
object maintains an internal

or

value, which is called its
value
Exposed
=Window]
interface
SVGAngle

// Angle Unit Types
const unsigned short
SVG_ANGLETYPE_UNKNOWN
= 0;
const unsigned short
SVG_ANGLETYPE_UNSPECIFIED
= 1;
const unsigned short
SVG_ANGLETYPE_DEG
= 2;
const unsigned short
SVG_ANGLETYPE_RAD
= 3;
const unsigned short
SVG_ANGLETYPE_GRAD
= 4;

readonly attribute unsigned short
unitType
attribute float
value
attribute float
valueInSpecifiedUnits
attribute DOMString
valueAsString

undefined
newValueSpecifiedUnits
(unsigned short unitType, float valueInSpecifiedUnits);
undefined
convertToSpecifiedUnits
(unsigned short unitType);
};
The numeric angle unit type constants defined on
SVGAngle
are used
to represent the type of an
SVGAngle
's
value
Their meanings are as follows:
Constant
Meaning
SVG_ANGLETYPE_UNSPECIFIED
A unitless

interpreted as a value in degrees.
SVG_ANGLETYPE_DEG
An

with a
deg
unit.
SVG_ANGLETYPE_RAD
An

with a
rad
unit.
SVG_ANGLETYPE_GRAD
An

with a
grad
unit.
SVG_ANGLETYPE_UNKNOWN
Some other type of value.
The use of numeric angle unit type constants is an anti-pattern and
new constant values will not be introduced for any other units or angle types supported by
SVGAngle
. If other types of angles are supported and used, the
SVGAngle
uses the
SVG_ANGLETYPE_UNKNOWN
unit type. See below for details on how the other properties of an
SVGAngle
operate with these types of angles.
The
unitType
IDL attribute represents
the type of value that the
SVGAngle
's
value
is.
On getting
unitType
, the following steps
are run:
If the
SVGAngle
's
value
is a unitless

or a

with a
deg
rad
or
grad
unit, then return the corresponding constant
value from the angle unit type table above.
Otherwise, return
SVG_ANGLETYPE_UNKNOWN
For example, for an

with a
turn
unit,
SVG_ANGLETYPE_UNKNOWN
would be returned.
The
value
IDL attribute represents
the
SVGAngle
's
value
in degrees.
On getting
value
, the following steps
are run:
Let
value
be the
SVGAngle
's
value
If
value
is a

, return that number.
Return the result of converting
value
to an angle in degrees.
On setting
value
, the following steps
are run:
If the
SVGAngle
object is
read only
, then
throw
NoModificationAllowedError
Let
value
be the value being assigned to
value
Set the
SVGAngle
's
value
to a

whose value is
value
If the
SVGAngle
reflects the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
valueInSpecifiedUnits
IDL attribute represents
the numeric factor of the
SVGAngle
's
value
On getting
valueInSpecifiedUnits
, the following steps
are run:
Let
value
be the
SVGAngle
's
value
If
value
is a

, return that number.
Otherwise,
value
is an

value. Return
the numeric factor before its unit.
On setting
valueInSpecifiedUnits
, the following steps
are run:
If the
SVGAngle
object is
read only
, then
throw
NoModificationAllowedError
Let
value
be the value being assigned to
valueInSpecifiedUnits
If the
SVGAngle
's
value
is a

, then update its value to
value
Otherwise, if the
SVGAngle
's
value
is an

then update its numeric factor to
value
If the
SVGAngle
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
valueAsString
IDL attribute represents
the
SVGAngle
's
value
as a string.
On getting
valueAsString
, the following steps
are run:
Let
value
be the
SVGAngle
's
value
Let
string
be an empty string.
Let
factor
be
value
's numeric factor,
if it is an

or
value
itself it is a

Append to
string
an implementation
specific string that, if parsed as a

using CSS syntax,
would return the number value closest to
factor
, given the
implementation's supported
real number precision
If
value
is an

then append to
string
the canonical spelling of
value
's unit.
Return
string
On setting
valueAsString
, the following steps
are run:
If the
SVGAngle
object is
read only
, then
throw
NoModificationAllowedError
Let
value
be the value being assigned to
valueAsString
Parse
value
using the CSS syntax


].
If parsing failed, then
throw
SyntaxError
Otherwise, parsing succeeded. Set
SVGAngle
's
value
to the parsed value.
If the
SVGAngle
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
newValueSpecifiedUnits
method is used to set the
SVGAngle
's value in a typed manner. When
newValueSpecifiedUnits(unitType, valueInSpecifiedUnits) is called, the following
steps are run:
If the
SVGAngle
object is
read only
, then
throw
NoModificationAllowedError
If
unitType
is
SVG_ANGLETYPE_UNKNOWN
or is a value that does not appear in the angle unit type table above,
then
throw
NotSupportedError
Set
SVGAngle
's
value
depending
on the value of
unitType
SVG_ANGLETYPE_UNSPECIFIED

whose value is
valueInSpecifiedUnits
anything else
an

whose numeric factor is
valueInSpecifiedUnits
and whose unit is as indicated by the angle unit type table above
If the
SVGAngle
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
The
convertToSpecifiedUnits
method is used to convert the
SVGAngle
's value to a specific type.
When convertToSpecifiedUnits(unitType) is called, the following steps are run:
If the
SVGAngle
object is
read only
, then
throw
NoModificationAllowedError
If
unitType
is
SVG_ANGLETYPE_UNKNOWN
or is a value that does not appear in the angle unit type table above,
then
throw
NotSupportedError
Let
degrees
be the value that would be returned from the
value
member.
If
unitType
is
SVG_ANGLETYPE_UNSPECIFIED
, then:
Set the
SVGAngle
's
value
to a

whose value is
degrees
Otherwise:
Set the
SVGAngle
's
value
to the result of
converting
degrees
to an

with the unit
found by looking up
unitType
in the angle unit type table above.
If the
SVGAngle
reflects the base value
of a
reflected
attribute or
reflects an element of the base value
of a
reflected
attribute,
then
reserialize
the reflected attribute.
4.5.4. List interfaces
SVG 2 Requirement:
Make the SVGList* interfaces a bit more like other lists/arrays.
Resolution:
Add array style indexing and .length and .item to svg list types.
Purpose:
To align with other array types (e.g. NodeList). Already implemented in Opera and Firefox.
Owner:
Erik (
ACTION-2975
Status:
Done
Some SVG attributes contain lists of values, and to represent these values
there are a number of SVG DOM
list interfaces
, one
for each required element type –
SVGNumberList
SVGLengthList
SVGPointList
SVGTransformList
and
SVGStringList
The first four are used to represent the base and
animated components of
SVGAnimatedNumberList
SVGAnimatedLengthList
SVGAnimatedPoints
and
SVGTransformList
objects,
while the fifth,
SVGStringList
, is used to
reflect
few unanimated attributes that take a list of strings.
Most
list interfaces
take the following form:
interface
SVG
Name
List

readonly attribute unsigned long
length
readonly attribute unsigned long
numberOfItems

undefined
clear
();
Type
initialize
Type
newItem);
getter
Type
getItem
(unsigned long index);
Type
insertItemBefore
Type
newItem, unsigned long index);
Type
replaceItem
Type
newItem, unsigned long index);
Type
removeItem
(unsigned long index);
Type
appendItem
Type
newItem);
setter
undefined (unsigned long index,
Type
newItem);
};
where
Name
is a descriptive name for the list element's
("Number", "Length", "Point", "Transform" or "String") and
Type
is the IDL type of the
list's elements (
SVGNumber
SVGLength
DOMPoint
SVGTransform
or
DOMString
).
The
SVGTransformList
interface takes the above form but has
two additional methods on it.
All
list interface
objects apart from
SVGTransformList
reflect the base value of a reflected content
attribute.
SVGTransformList
objects reflect a presentation
attribute (
‘transform’
gradientTransform
or
patternTransform
).
All
list interface
objects are associated with a particular element.
Unlike
SVGLength
and similar objects, there are no "detached"
list interface
objects.
list interface
object maintains an internal list of elements,
which is referred to in the text below simply as "the list".
The IDL attributes and methods are used to inspect and manipulate elements
of the list. The list can also be changed in response to
changes to the reflected content attribute and to animation of
the content attribute (or, for
SVGTransformList
objects,
in response to changes to the computed value of the
transform
property).
list interface
object can be designated as
read only
, which means that attempts to modify the object will result
in an exception being thrown, as described below.
list interface
objects
reflected through the animVal IDL attribute are always
read only
list interface
object
is
synchronized
by running
the following steps:
Let
value
be the base value of the
reflected content attribute (using the attribute's
initial value
if it is not present or invalid).
Let
length
be the number of items in the list.
Let
new length
be the number of values in
value
If
value
is the keyword
none
(as supported by the
transform
property),
new length
is 0.
If the list element type is
SVGNumber
SVGLength
DOMPoint
or
SVGTransform
, then:
If
length
new length
, then:
Detach
each object in the list at an index
greater than or equal to
new length
Truncate the list to length
new length
Set
length
to
new length
While
length
new length
Let
item
be a newly created
object of the list element type.
Attach
item
to this
list interface
object.
Append
item
to the list.
Set
length
to
length
+ 1.
Let
index
be 0.
While
index
length
Let
item
be the object in the list at index
index
Let
be the value in
value
at index
index
Set
item
's value to
If
item
is an
SVGTransform
object, then
set the components of its
matrix object
to match the new transform function value.
Set
index
to
index
+ 1.
Otherwise, the list element type is
DOMString
Replace the list with a new list consisting
of the values in
value
Whenever a list element object is to be
detached
the following steps are run, depending on the list element type:
SVGNumber
Set the
SVGNumber
to no longer be
associated
with any element.
If the
SVGNumber
is
read only
set it to be no longer read only.
SVGLength
Set the
SVGLength
to no longer be
associated
with any element.
If the
SVGLength
is
read only
set it to be no longer read only. Set the
SVGLength
to have
unspecified
directionality
DOMPoint
Set the
DOMPoint
to no longer be
associated
with any element.
If the
DOMPoint
is
read only
set it to be no longer read only.
SVGTransform
Set the
SVGTransform
to no longer be
associated
with any element.
If the
SVGTransform
is
read only
set it to be no longer read only.
DOMString
Nothing is done.
Whenever a list element object is to be
attached
the following steps are run, depending on the list element type:
SVGNumber
Associate
the
SVGNumber
with the element that the
list interface
object is associated with. Additionally, depending on which IDL attribute
the
list interface
object is reflected through:
baseVal
Set the
SVGNumber
to
reflect an
element of the base value
animVal
Set the
SVGNumber
to
reflect an
element of the base value
SVGLength
Associate
the
SVGLength
with the element that the
list interface
object is associated with and set its
directionality
to that
specified by the attribute being reflected.
Additionally, depending on which IDL attribute the
list interface
object is reflected through:
baseVal
Set the
SVGLength
to
reflect an
element of the base value
animVal
Set the
SVGLength
to
reflect an
element of the base value
. Set the
SVGLength
to be
read only
DOMPoint
Associate
the
DOMPoint
with the element that the
list interface
object is associated with.
Additionally, depending on which IDL attribute the
list interface
object is reflected through:
baseVal
Set the
DOMPoint
to
reflect an
element of the base value
animVal
Set the
DOMPoint
to
reflect an
element of the base value
SVGTransform
Associate
the
SVGTransform
with the element that the
list interface
object is associated with.
Set the
SVGTransform
to
reflect an
element of a presentation attribute value
DOMString
Nothing is done.
The
supported property indices
of a
list interface
object is the set of all non-negative integers
less than the length of the list.
The
length
and
numberOfItems
IDL attributes
represents the length of the list, and on getting simply return
the length of the list.
The
clear
method is used to
remove all items in the list. When clear() is called, the following steps are run:
If the list is
read only
, then
throw
NoModificationAllowedError
Detach
and then remove all elements in the list.
If the list
reflects
an attribute, or represents the
base value of an object that
reflects
an attribute, then
reserialize
the reflected attribute.
The
initialize
method
is used to clear the list and add a single, specified value to it.
When initialize(
newItem
) is called, the following steps are run:
If the list is
read only
, then
throw
NoModificationAllowedError
Detach
and then remove all elements in the list.
If
newItem
is an object type, and
newItem
is not a detached object, then set
newItem
to be
a newly created object of the same type as
newItem
and which has the same (number or length) value.
Attach
newItem
to the
list interface
object.
Append
newItem
to this list.
If the list
reflects
an attribute, or represents the
base value of an object that
reflects
an attribute, then
reserialize
the reflected attribute.
Return
newItem
The
getItem
method is used
to get an item from the list at the specified position. When
getItem(
index
) is called, the following steps are run:
If
index
is greater than or equal to the length
of the list, then
throw
an
IndexSizeError
Return the element in the list at position
index
Note that if the list's element type is an object type,
such as
SVGLength
, then a reference to that object and not
a copy of it is returned.
The
insertItemBefore
method is used to insert an element into the list at a specific position.
When insertItemBefore(
newItem
index
) is called,
the following steps are run:
If the list is
read only
, then
throw
NoModificationAllowedError
If
newItem
is an object type, and
newItem
is not a detached object, then set
newItem
to be
a newly created object of the same type as
newItem
and which has the same (number or length) value.
If
index
is greater than the length of the list, then
set
index
to be the list length.
Insert
newItem
into the list at index
index
Attach
newItem
to the
list interface
object.
If the list
reflects
an attribute, or represents the
base value of an object that
reflects
an attribute, then
reserialize
the reflected attribute.
Return
newItem
The
replaceItem
method
is used to replace an existing item in the list with a new item.
When replaceItem(
newItem
index
) is called, the
following steps are run:
If the list is
read only
, then
throw
NoModificationAllowedError
If
index
is greater than or equal to the length of
the list, then
throw
an
IndexSizeError
If
newItem
is an object type, and
newItem
is not a detached object, then set
newItem
to be
a newly created object of the same type as
newItem
and which has the same (number or length) value.
Detach
the element in the list at index
index
Replace the element in the list at index
index
with
newItem
Attach
newItem
to the
list interface
object.
If the list
reflects
an attribute, or represents the
base value of an object that
reflects
an attribute, then
reserialize
the reflected attribute.
Return
newItem
The
removeItem
method
is used to remove an item from the list. When removeItem(
index
is called, the following steps are run:
If the list is
read only
, then
throw
NoModificationAllowedError
If
index
is greater than or equal to the length of
the list, then
throw
an
IndexSizeError
with code.
Let
item
be the list element at index
index
Detach
item
Remove the list element at index
index
Return
item
The
appendItem
method
is used to append an item to the end of the list. When appendItem(
newItem
is called, the following steps are run:
If the list is
read only
, then
throw
NoModificationAllowedError
If
newItem
is an object type, and
newItem
is not a detached object, then set
newItem
to be
a newly created object of the same type as
newItem
and which has the same (number or length) value.
Let
index
be the length of the list.
Append
newItem
to the end of the list.
Attach
newItem
to the
list interface
object.
If the list
reflects
an attribute, or represents the
base value of an object that
reflects
an attribute, then
reserialize
the reflected attribute.
Return
newItem
The behavior of the
indexed property setter
is the same as that for the
replaceItem
method.
4.5.5. Interface SVGNumberList
The
SVGNumberList
interface is a
list interface
whose
elements are
SVGNumber
objects. An
SVGNumberList
object
represents a list of numbers.
Exposed
=Window]
interface
SVGNumberList

readonly attribute unsigned long
length
readonly attribute unsigned long
numberOfItems

undefined
clear
();
SVGNumber
initialize
SVGNumber
newItem);
getter
SVGNumber
getItem
(unsigned long index);
SVGNumber
insertItemBefore
SVGNumber
newItem, unsigned long index);
SVGNumber
replaceItem
SVGNumber
newItem, unsigned long index);
SVGNumber
removeItem
(unsigned long index);
SVGNumber
appendItem
SVGNumber
newItem);
setter
undefined (unsigned long index,
SVGNumber
newItem);
};
The behavior of all of the interface members of
SVGNumberList
are
defined in the
List interfaces
section above.
4.5.6. Interface SVGLengthList
The
SVGLengthList
interface is a
list interface
whose
elements are
SVGLength
objects. An
SVGLengthList
object
represents a list of lengths.
Exposed
=Window]
interface
SVGLengthList

readonly attribute unsigned long
length
readonly attribute unsigned long
numberOfItems

undefined
clear
();
SVGLength
initialize
SVGLength
newItem);
getter
SVGLength
getItem
(unsigned long index);
SVGLength
insertItemBefore
SVGLength
newItem, unsigned long index);
SVGLength
replaceItem
SVGLength
newItem, unsigned long index);
SVGLength
removeItem
(unsigned long index);
SVGLength
appendItem
SVGLength
newItem);
setter
undefined (unsigned long index,
SVGLength
newItem);
};
The behavior of all of the interface members of
SVGLengthList
are
defined in the
List interfaces
section above.
4.5.7. Interface SVGStringList
The
SVGStringList
interface is a
list interface
whose
elements are
DOMString
values. An
SVGStringList
object
represents a list of strings.
Exposed
=Window]
interface
SVGStringList

readonly attribute unsigned long
length
readonly attribute unsigned long
numberOfItems

undefined
clear
();
DOMString
initialize
(DOMString newItem);
getter DOMString
getItem
(unsigned long index);
DOMString
insertItemBefore
(DOMString newItem, unsigned long index);
DOMString
replaceItem
(DOMString newItem, unsigned long index);
DOMString
removeItem
(unsigned long index);
DOMString
appendItem
(DOMString newItem);
setter
undefined (unsigned long index, DOMString newItem);
};
The behavior of all of the interface members of
SVGStringList
are
defined in the
List interfaces
section above.
4.6. DOM interfaces for reflecting animatable SVG attributes
The following interfaces are used to represent the reflected value
of animatable content attributes.
They each consist of two component objects, representing the same data:
baseVal
and
animVal
The
baseVal
(base value) object is modifiable,
to update the corresponding attribute value.
In SVG 1.1, the
animVal
attribute of the SVG DOM interfaces represented the
current animated value of the reflected attribute. In this version of SVG,
animVal
no longer represents the current animated value and is instead an
alias of
baseVal
4.6.1. Interface SVGAnimatedBoolean
An
SVGAnimatedBoolean
object is used to
reflect
an
animatable attribute that takes a boolean value.
Exposed
=Window]
interface
SVGAnimatedBoolean
attribute boolean
baseVal
readonly attribute boolean
animVal
};
The
baseVal
and
animVal
IDL attributes
both represent the current non-animated value of the reflected attribute.
On getting
baseVal
or
animVal
the following steps are run:
Let
value
be the value of the reflected attribute,
or the empty string if it is not present.
If
value
is not "true" or "false", then set
value
to the reflected attribute's
initial value
Return true if
value
is "true", and false otherwise.
On setting
baseVal
the reflected attribute is set to "true" if the value is true, and "false"
otherwise.
4.6.2. Interface SVGAnimatedEnumeration
An
SVGAnimatedEnumeration
object is used to
reflect
an animatable attribute that takes a keyword value (such as
the
method
attribute on
textPath
) or to reflect
the type of value that an animatable attribute has (done
only by the
orientType
IDL attribute for the
marker
element's
orient
attribute).
Exposed
=Window]
interface
SVGAnimatedEnumeration
attribute unsigned short
baseVal
readonly attribute unsigned short
animVal
};
For
SVGAnimatedEnumeration
objects that
reflect
an
animatable attribute that takes only a keyword value, the
baseVal
and
animVal
IDL attributes
represents the current non-animated value of the reflected attribute.
For
orientType
they represent the type of the current non-animated value of the
reflected
orient
attribute. On getting
baseVal
or
animVal
, the
following steps are run:
Let
value
be the value of the reflected attribute
(using the attribute's
initial value
if it is not present
or invalid).
Return the
numeric type value
for
value
, according to the reflecting IDL attribute's
definition.
On setting
baseVal
the following steps are run:
Let
value
be the value being assigned to
baseVal
If
value
is 0 or is not the
numeric type value
for any value of the reflected attribute, then throw a
TypeError
Otherwise, if the reflecting IDL attribute is
orientType
and
value
is
SVG_MARKER_ORIENT_ANGLE
then set the reflected attribute to the string "0".
Otherwise,
value
is the
numeric type value
for a specific, single keyword value for the reflected attribute.
Set the reflected attribute to that value.
4.6.3. Interface SVGAnimatedInteger
An
SVGAnimatedInteger
object is used to
reflect
an
animatable attribute that takes an integer value (such as
numOctaves
on
feTurbulence
). It is also
used to reflect one part of an animatable attribute that takes
an integer followed by an optional second integer (such as
order
on
feConvolveMatrix
).
This
SVGAnimatedInteger
interface
is not used in this specification, however the
Filter Effects
specification has a number of uses of it.
Exposed
=Window]
interface
SVGAnimatedInteger
attribute long
baseVal
readonly attribute long
animVal
};
For
SVGAnimatedInteger
objects that
reflect
an animatable attribute that takes a single integer value, the
baseVal
and
animVal
IDL attributes
represent the current non-animated value of the reflected attribute.
For those that reflect one integer of an attribute that takes an
integer followed by an optional second integer, they represent the
current non-animated value of one of the two integers. On getting
baseVal
or
animVal
, the
following steps are run:
Let
value
be the value of the reflected attribute
(using the attribute's
initial value
if it is not present
or invalid).
If the reflected attribute is defined to take an integer
followed by an optional second integer, then:
If this
SVGAnimatedInteger
object reflects the
first integer, then return the first value in
value
Otherwise, this
SVGAnimatedInteger
object reflects the
second integer. Return the second value in
value
if it has been
explicitly specified, and if not, return the implicit value
as described in the definition of the attribute.
For example, the definition of
order
says that the implicit second integer is the same as the explicit
first integer.
Otherwise, the reflected attribute is defined to take a single
integer value. Return
value
On setting
baseVal
the following steps are run:
Let
value
be the value being assigned to
baseVal
Let
new
be a list of integers.
If the reflected attribute is defined to take an integer
followed by an optional second integer, then:
Let
current
be the value of the reflected attribute
(using the attribute's
initial value
if it is not present
or invalid).
Let
first
be the first integer in
current
Let
second
be the second integer in
current
if it has been explicitly specified, and if not, the implicit value
as described in the definition of the attribute.
If this
SVGAnimatedInteger
object reflects the
first integer, then set
first
to
value
Otherwise, set
second
to
value
Append
first
to
new
Append
second
to
new
Otherwise, the reflected attribute is defined to take a single
integer value. Append
value
to
new
Set the content attribute to a string consisting of each integer
in
new
serialized to an implementation specific string that,
if parsed as an

using CSS syntax, would return that
integer, joined and separated by a single U+0020 SPACE character.
4.6.4. Interface SVGAnimatedNumber
An
SVGAnimatedNumber
object is used to
reflect
an
animatable attribute that takes a number value (such as
pathLength
on
path
). It is also
used to reflect one part of an animatable attribute that takes
an number followed by an optional second number (such as
kernelUnitLength
on
feDiffuseLighting
).
Exposed
=Window]
interface
SVGAnimatedNumber
attribute float
baseVal
readonly attribute float
animVal
};
For
SVGAnimatedNumber
objects that
reflect
an animatable attribute that takes a single number value, the
baseVal
and
animVal
IDL attributes
represent the current non-animated value of the reflected attribute.
For those that reflect one number of an attribute that takes a
number followed by an optional second number, they represent the
current non-animated value of one of the two numbers. On getting
baseVal
or
animVal
, the
following steps are run:
Let
value
be the value of the reflected attribute
(using the attribute's
initial value
if it is not present
or invalid).
If the reflected attribute is defined to take an number
followed by an optional second number, then:
If this
SVGAnimatedNumber
object reflects the
first number, then return the first value in
value
Otherwise, this
SVGAnimatedNumber
object reflects the
second number. Return the second value in
value
if it has been
explicitly specified, and if not, return the implicit value
as described in the definition of the attribute.
For example, the definition of
kernelUnitLength
says that the implicit second number is the same as the explicit
first number.
Otherwise, the reflected attribute is defined to take a single
number value. Return
value
On setting
baseVal
the following steps are run:
Let
value
be the value being assigned to
baseVal
Let
new
be a list of numbers.
If the reflected attribute is defined to take an number
followed by an optional second number, then:
Let
current
be the value of the reflected attribute
(using the attribute's
initial value
if it is not present
or invalid).
Let
first
be the first number in
current
Let
second
be the second number in
current
if it has been explicitly specified, and if not, the implicit value
as described in the definition of the attribute.
If this
SVGAnimatedNumber
object reflects the
first number, then set
first
to
value
Otherwise, set
second
to
value
Append
first
to
new
Append
second
to
new
Otherwise, the reflected attribute is defined to take a single
number value. Append
value
to
new
Set the content attribute to a string consisting of each number
in
new
serialized to an implementation specific string that,
if parsed as an

using CSS syntax, would return the
value closest to the number (given the implementation's supported
Precision
real number precision),
joined and separated by a single U+0020 SPACE character.
4.6.5. Interface SVGAnimatedLength
An
SVGAnimatedLength
object is used to
reflect
either
(a) an animatable attribute that takes a


or

value, or (b) a
CSS property that takes one of these values and its corresponding
presentation attribute.
Exposed
=Window]
interface
SVGAnimatedLength
SameObject
] readonly attribute
SVGLength
baseVal
SameObject
] readonly attribute
SVGLength
animVal
};
The
baseVal
and
animVal
IDL attributes
represent the current value of the reflected content attribute.
On getting
baseVal
or
animVal
an
SVGLength
object is returned that:
either
reflects the base value
of the
reflected attribute or
reflects the
given presentation attribute
is
associated with
the SVG element that
the object with the reflecting IDL attribute of type
SVGAnimatedLength
was obtained from, and
has a
directionality
as defined by the
specific reflected attribute.
4.6.6. Interface SVGAnimatedAngle
An
SVGAnimatedAngle
object is used to
reflect
the

value of the animated
orient
attribute on
marker
, through the
orientAngle
IDL attribute.
Exposed
=Window]
interface
SVGAnimatedAngle
SameObject
] readonly attribute
SVGAngle
baseVal
SameObject
] readonly attribute
SVGAngle
animVal
};
The
baseVal
and
animVal
IDL attributes represent
the current non-animated

value of the
reflected
orient
attribute. On getting
baseVal
or
animVal
, an
SVGAngle
object is returned that:
reflects the base value
of the
reflected
orient
attribute, and
is
associated with
the SVG
marker
element that the object with the reflecting IDL attribute of type
SVGAnimatedAngle
was obtained from.
4.6.7. Interface SVGAnimatedString
An
SVGAnimatedString
object is used to
reflect
an
animatable attribute that takes a string value. It can optionally
be defined to additionally reflect a second, deprecated attribute.
Exposed
=Window]
interface
SVGAnimatedString
attribute (DOMString or TrustedScriptURL)
baseVal
readonly attribute DOMString
animVal
};
The
baseVal
and
animVal
IDL attributes
represent the current non-animated value of the reflected attribute.
On getting
baseVal
or
animVal
the following steps are run:
If the reflected attribute is not present, then:
If the
SVGAnimatedString
object is defined to additionally
reflect a second, deprecated attribute, and that attribute is present,
then return its value.
Otherwise, if the reflected attribute has an
initial value
then return it.
Otherwise, return the empty string.
Otherwise, the reflected attribute is present. Return its value.
For the
href
member on the
SVGURIReference
interface, this will result in
the deprecated
xlink:href
attribute being returned if it is
present and the
‘href’
attribute is not,
and in the
‘href’
attribute being
returned in all other cases.
On setting
baseVal
the following steps are run:
If the reflected attribute’s element is an
SVGScriptElement
, let
value
be the result of
executing the
Get Trusted Type compliant string
algorithm, with
TrustedScriptURL
reflected attribute’s Document's relevant global object, 'SVGScriptElement href', and 'script'.
Otherwise, let value be the specified value.
If the reflected attribute is not present,
the
SVGAnimatedString
object is defined to additionally reflect
a second, deprecated attribute, and that deprecated attribute is present,
then set that deprecated attribute to value.
Otherwise, set the reflected attribute to value.
SVG does not have a complete script processing model
yet
Trusted Types
assumes that the attribute and
text body modification protections behave similarly to ones for HTML scripts.
For the
href
member on the
SVGURIReference
interface, this will result in
the deprecated
xlink:href
attribute being set if it is
present and the
‘href’
attribute is not,
and in the
‘href’
attribute being
set in all other cases.
4.6.8. Interface SVGAnimatedRect
An
SVGAnimatedRect
object is used to
reflect
an
animatable attribute that takes a rectangle value as specified
by an
width
and
height
In this specification the only attribute to be
reflected as an
SVGAnimatedRect
is
viewBox
Exposed
=Window]
interface
SVGAnimatedRect
SameObject
] readonly attribute
DOMRect
baseVal
SameObject
] readonly attribute
DOMRectReadOnly
animVal
};
The
baseVal
and
animVal
IDL
attributes represent the current non-animated rectangle value of
the reflected attribute. On getting
baseVal
or
animVal
DOMRect
object is returned.
Upon creation of the
baseVal
or
animVal
DOMRect
objects, and afterwards whenever the reflected content attribute
is added, removed, or changed, the following steps are run:
Let
value
be the value of the reflected attribute
(using the attribute's
initial value
if it is not present
or invalid).
Let
width
and
height
be those corresponding components of
value
Set the
DOMRect
object's
x coordinate
y coordinate
width
and
height
to
width
and
height
respectively.
Whenever the
x coordinate
y coordinate
width
or
height
property
of the
baseVal
or
animVal
DOMRect
object changes, except as part of the previous algorithm that
reflects the value of the content attribute into the
DOMRect
, the reflected
content attribute must be
reserialized
4.6.9. Interface SVGAnimatedNumberList
An
SVGAnimatedNumberList
object is used to
reflect
an animatable
attribute that takes a list of

values.
Exposed
=Window]
interface
SVGAnimatedNumberList
SameObject
] readonly attribute
SVGNumberList
baseVal
SameObject
] readonly attribute
SVGNumberList
animVal
};
The
baseVal
and
animVal
IDL attributes
represent the current non-animated value of the reflected attribute.
On getting
baseVal
or
animVal
an
SVGNumberList
object is returned that reflects the base value
of the reflected attribute.
4.6.10. Interface SVGAnimatedLengthList
An
SVGAnimatedLengthList
object is used to
reflect
an animatable
attribute that takes a list of


or

values.
Exposed
=Window]
interface
SVGAnimatedLengthList
SameObject
] readonly attribute
SVGLengthList
baseVal
SameObject
] readonly attribute
SVGLengthList
animVal
};
The
baseVal
or
animVal
IDL attributes
represent the current non-animated value of the reflected attribute.
On getting
baseVal
or
animVal
an
SVGLengthList
object is returned that reflects the base value
of the reflected attribute.
4.7. Other DOM interfaces
4.7.1. Interface SVGUnitTypes
The
SVGUnitTypes
interface defines a commonly used set of constants
used for reflecting
gradientUnits
patternContentUnits
and
other similar attributes.
Exposed
=Window]
interface
SVGUnitTypes
// Unit Types
const unsigned short
SVG_UNIT_TYPE_UNKNOWN
= 0;
const unsigned short
SVG_UNIT_TYPE_USERSPACEONUSE
= 1;
const unsigned short
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX
= 2;
};
The unit type constants defined on
SVGUnitTypes
have the following meanings:
Constant
Meaning
SVG_UNIT_TYPE_USERSPACEONUSE
Corresponds to the
'userSpaceOnUse'
attribute value.
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX
Corresponds to the
'objectBoundingBox'
attribute value.
SVG_UNIT_TYPE_UNKNOWN
Some other type of value.
4.7.2. Mixin SVGTests
The
SVGTests
interface is used to reflect
conditional processing attributes
, and is mixed in to other
interfaces for elements that support these attributes.
interface mixin
SVGTests
SameObject
] readonly attribute
SVGStringList
requiredExtensions
SameObject
] readonly attribute
SVGStringList
systemLanguage
};
The
requiredExtensions
IDL attribute
reflects
the
requiredExtensions
content attribute.
The
systemLanguage
IDL attribute
reflects
the
systemLanguage
content attribute.
4.7.3. Mixin SVGFitToViewBox
The
SVGFitToViewBox
interface is used to reflect
the
viewBox
and
preserveAspectRatio
attributes,
and is mixed in to other interfaces for elements that support
these two attributes.
interface mixin
SVGFitToViewBox
SameObject
] readonly attribute
SVGAnimatedRect
viewBox
SameObject
] readonly attribute
SVGAnimatedPreserveAspectRatio
preserveAspectRatio
};
The
viewBox
IDL attribute
reflects
the
viewBox
content attribute.
The
preserveAspectRatio
IDL attribute
reflects
the
preserveAspectRatio
content attribute.
4.7.4. Mixin SVGURIReference
The
SVGURIReference
interface is used to reflect
the
‘href’
attribute and the deprecated
xlink:href
attribute.
interface mixin
SVGURIReference
SameObject
] readonly attribute
SVGAnimatedString
href
};
The
href
IDL attribute
represents the value of the
‘href’
attribute, and, on elements that are defined to support it,
the deprecated
xlink:href
attribute. On getting
href
, an
SVGAnimatedString
object is returned that:
reflects the
‘href’
attribute, and
if the element is defined to support the deprecated
xlink:href
attribute, additionally reflects that deprecated attribute.
The
SVGAnimatedString
interface is defined
to reflect, through its
baseVal
and
animVal
members, the deprecated
xlink:href
attribute, if that attribute is
present and the
‘href’
is not, and to
reflect the
‘href’
attribute in all
other circumstances.
Animation elements
treat
attributeName='xlink:href'
as being an alias for targeting the
‘href’
attribute.
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

xmlns:svg="http://www.w3.org/2000/svg">






This example shows a slightly more complex (i.e., it contains
multiple rectangles) stand-alone, self-contained SVG document:


Four separate rectangles

fill="none" stroke="blue" stroke-width=".02cm" />

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:


Two groups, each of two rectangles

fill="none" stroke="blue" stroke-width=".02cm"/>

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

width="200" height="100" viewBox="0 0 200 100">


Two circles, one of which is a re-styled clone of the other.
This file demonstrates one of the cases where
the shadow-DOM style matching rules in SVG 2
have a different effect than the SVG 1.1 style cloning rules.
The original circle on the left
should have blue fill
and green stroke.
In a conforming SVG 1.1 user agent,
the re-used circle on the right
should have orange fill and green stroke.
In a conforming SVG 2 user agent,
the re-used circle should have orange fill and purple stroke.
In all cases,
the stroke should be partially transparent
and 20 units wide,
relative to a total circle diameter of 100 units.



stroke-width="20" />



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



This is a financial report
The global description uses markup from the
myfoo namespace.
widget $growth
$three $graph-bar
1998 $through 2000


xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
xmlns:dc = "http://purl.org/dc/elements/1.1/" >
dc:title="MyFoo Financial Report"
dc:description="$three $bar $thousands $dollars $from 1998 $through 2000"
dc:publisher="Example Organization"
dc:date="2000-04-11"
dc:format="image/svg+xml"
dc:language="en" >


Irving Bird
Mary Lambert






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:



title="Sales by Region">







This chart includes private data in another namespace



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.
Chapter 6: Styling
6.1. Styling SVG content using CSS
Elements in an SVG document can be styled using CSS.
Most visual characteristics and some aspects of element
geometry are controlled using CSS
properties
For example, the
fill
property controls the paint used to
fill the inside of a shape, and the
width
and
height
properties are used to control the size
of a
rect
element.
SVG user agents must support all of the CSS styling
mechanisms described in this chapter.
In SVG 1.1, support for inline style sheets
using the
style
element and
style
was not required. In SVG 2,
these are required.
6.2. Inline style sheets: the
‘style’
element
SVG 2 Requirement:
Add HTML5
‘style’
element attributes to SVG's
style
element.
Resolution:
SVG 2
‘style’
element shall be aligned with the HTML5
‘style’
element.
Purpose:
To not surprise authors with different behavior for the
‘style’
element in HTML and SVG content.
Owner:
Cameron (
ACTION-3277
The
style
element allows
style sheets to be embedded directly within SVG content.
SVG's
style
element has the same
attributes as the
corresponding
element in HTML
style
Categories:
Never-rendered element
Content model:
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
type
media
title
DOM Interfaces:
SVGStyleElement
Attribute definitions:
Name
Value
Initial value
Animatable
type
(see below)
text/css
no
This attribute specifies the style sheet language of
the element's contents, as a
media type
rfc2046
].
If the attribute is not specified, then the
style sheet language is assumed to be CSS.
Name
Value
Initial value
Animatable
media
(see below)
all
no
This attribute specifies a media query that must be
matched for the style sheet to apply. Its value is parsed
as a
media_query_list
If not specified, the style sheet applies unconditionally.
Name
Value
Initial value
Animatable
title
(see below)
(none)
no
This attribute specifies a title for the style sheet,
which is used when exposing and selecting between alternate
style sheets. The attribute takes any value.
The semantics and processing of a
style
and its
attributes must be the same as is defined for the
HTML
‘style’
element
The style sheet's text content is never directly rendered;
the
display
value for the
style
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.
6.3. External style sheets: the effect of the HTML
‘link’
element
An
HTML
‘link’
element
in an SVG document (that is,
an element in the HTML namespace with local name "link")
with its
‘rel’
attribute set to
'stylesheet'
must be processed
as defined in the HTML specification and cause external style sheets to be
loaded and applied to the document. Such elements in HTML documents outside
of an inline SVG fragment must also apply to the SVG content.
Because the element is required to be in the HTML namespace, it
is not possible for an
HTML
‘link’
element
to be parsed as
part of an inline SVG fragment in a text/html document. However, when
parsing an SVG document using XML syntax, XML namespace declarations
can be used to place the element in the HTML namespace.
Note that an alternative way to reference external style sheets
without using the
HTML
‘link’
element
is to use an @import
rule in an inline style sheet. For example:




would behave similarly to:




Or, in XML documents, external CSS style sheets may be included using the

processing instruction [
xml-stylesheet
].
6.4. Style sheets in HTML documents
When an SVG
style
or an HTML
‘style’
element is used in an HTML
document, those style sheets must apply to all HTML and
inline SVG content in the document. Similarly, any HTML
‘style’
element used in an SVG
document must also apply its style sheet to the document.
6.5. Element-specific styling: the
‘class’
and
‘style’
attributes
As with HTML, SVG supports the
class
and
style
attributes on all elements to support element-specific styling.
Attribute definitions:
Name
Value
Initial value
Animatable
class
set of space-separated tokens
[HTML]
(none)
yes
The
class
attribute assigns one or more class names to an element,
which can then be used for addressing by the styling language.
Name
Value
Initial value
Animatable
style
(see below)
(none)
no
The
style
attribute is used to supply a
CSS declaration of an element. The attribute is
parsed as a declaration-list
Aside from the way that the
class
attribute is reflected in the
SVG DOM (in the
className
IDL attribute on
SVGElement
), the semantics and behavior of the
class
and
style
attributes must be the same
as that for
the corresponding
attributes in HTML
In the following example, the
text
element is used in
conjunction with the
class
attribute to markup document messages. Messages appear in both
English and French versions.

Variable declared twice
Undeclared variable
Bad syntax for variable name

Variable déclarée deux fois
Variable indéfinie
Erreur de syntaxe pour variable
The following CSS style
rules would tell visual user agents to display informational
messages in green, warning messages in yellow, and error
messages in red:
text.info { fill: green; }
text.warning { fill: yellow; }
text.error { fill: red; }
This example shows how the
style
attribute can be
used to style
text
elements similarly to the previous example:
Variable declared twice
Undeclared variable
Bad syntax for variable name
6.6. Presentation attributes
Some styling properties can be specified not only in style sheets
and
style
attributes, but also in
presentation attributes
These are attributes whose name matches (or is similar to) a given CSS property
and whose value is parsed as a value of that property. Presentation
attributes contribute to the
author level
of the cascade, followed by all other author-level style sheets,
and have specificity 0.
Since presentation attributes are parsed as CSS values, not declarations, an
!important
declaration
within a presentation attribute will cause it to have an
invalid value
See
Attribute syntax
for details on how presentation attributes are parsed.
Not all style properties that can affect SVG rendering have a corresponding
presentation attribute.
Other attributes (which happen to share the name of a style property) must not be parsed as a
presentation attribute and must not affect CSS cascading and inheritance.
Also, only elements in the SVG namespace support presentation attributes.
Most SVG presentation attributes may be specified on any element in the SVG namespace
where there is not a name clash with an existing attribute.
However, the
geometry properties
only have equivalent presentation attributes
on designated elements.
Attributes of the same name on other elements must not affect CSS cascading and inheritance.
Except as noted in the table for the
transform
presentation attributes,
the presentation attribute name is the same as the property name, in lower-case letters.
Properties with a presentation attribute
Elements that support the presentation attribute
cx
cy
circle
and
ellipse
height
width
foreignObject
image
rect
svg
symbol
, and
use
circle
rx
ry
ellipse
and
rect
path
fill
Any element in the SVG namespace except for
animation elements
which have a different
fill
attribute.
transform
For historical reasons, the
transform
property gets represented by different presentation attributes depending on the SVG element it applies to:
transform
Any element in the SVG namespace with the exception of the
pattern
linearGradient
and
radialGradient
elements.
patternTransform
pattern
patternTransform
gets mapped to the
transform
CSS property
css-transforms-1
].
gradientTransform
linearGradient
and
radialGradient
elements.
gradientTransform
gets mapped to the
transform
CSS property [
css-transforms-1
].
alignment-baseline
baseline-shift
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
cursor
direction
display
dominant-baseline
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-vertical
image-rendering
letter-spacing
lighting-color
marker-end
marker-mid
marker-start
mask
mask-type
opacity
overflow
paint-order
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-overflow
text-rendering
transform-origin
unicode-bidi
vector-effect
visibility
white-space
word-spacing
writing-mode
Any element in the SVG namespace.
Note that
‘cx’
‘cy’
‘r’
‘x’
‘y’
‘width’
and
‘height’
attributes are not
always presentation attributes.
For example, the
attribute on
text
and
tspan
is not a presentation attribute for the
property,
and the
attribute on a
radialGradient
is not a presentation attribute for the
property.
In the future, any new properties that apply
to SVG content will not gain presentation attributes. Therefore,
authors are suggested to use styling properties, either through
inline
style
properties or style sheets,
rather than presentation attributes, for styling SVG content.
Animation of presentation attributes is equivalent to
animating the corresponding property.
6.7. Required properties
The following properties must be supported by all SVG user agents:
all properties defined in this specification
the
display
overflow
and
visibility
properties
CSS2
the
cursor
and
text-overflow
property
css-overflow-3
the
clip-path
clip-rule
and
mask
properties
css-masking-1
the
color
and
opacity
properties
css-color-3
the
color-interpolation-filters
filter
flood-color
flood-opacity
and
lighting-color
properties
filter-effects-1
the
isolation
property
compositing-1
the
transform
transform-box
and
transform-origin
properties
css-transforms-1
the
letter-spacing
text-align
text-align-last
text-indent
and
word-spacing
properties
css-text-3
the
white-space
property
css-text-4
the
vertical-align
dominant-baseline
alignment-baseline
, and
baseline-shift
properties
css-inline-3
the
direction
text-orientation
and
writing-mode
properties
css-writing-modes-3
the
font
font-family
font-feature-settings
font-kerning
font-size
font-size-adjust
font-stretch
font-style
font-variant
(along with its subproperties)
and
font-weight
properties
css-fonts-3
the
text-decoration
text-decoration-line
text-decoration-style
and
text-decoration-color
properties
css-text-decor-3
6.8. User agent style sheet
The following
user
agent style sheet
must be applied in all SVG user agents.
@namespace url(http://www.w3.org/2000/svg);
@namespace xml url(http://www.w3.org/XML/1998/namespace);

svg:not(:root), image, marker, pattern, symbol { overflow: hidden; }

*:not(svg),
*:not(foreignObject) > svg {
transform-origin: 0 0;

*[xml|space=preserve] {
white-space-collapse: preserve-spaces;

defs,
clipPath, mask, marker,
desc, title, metadata,
pattern, linearGradient, radialGradient,
script, style,
symbol {
display: none !important;
:host(use) > symbol {
display: inline !important;
:link, :visited {
cursor: pointer;
In addition,
all interactive user agents are required
to apply distinctive styles to
the
:focus
pseudo-class
(normally using the
outline
property)
and the
::selection
pseudo-element
(using an appropriate highlighting technique,
such as redrawing the selected glyphs with inverse colors).
An
!important
rule in a user agent stylesheet
over-rides all user and author styles
css-cascade-4
].
The display value for
never-rendered elements
and for
symbol
elements
can therefore not be changed.
A symbol must only be rendered if it is the direct child
of a shadow root whose host is a
use
element
(and must always be rendered if the host
use
element is rendered).
The other elements, and their child content, are never rendered directly.
CSS Transforms defines that the initial value for
transform-origin
is
50% 50%
Since elements in SVG must, by default, transform around their origin at (0, 0),
transform-origin
is overridden and set to a default value of
0 0
for all SVG elements
(except for root
svg
elements and
svg
elements that are the child of a
foreignObject
element or an element in a non-SVG namespace; these elements
must transform around their center).
css-transforms-1
The OpenType specification
requires an additional user agent style sheet
to be applied when processing
OPENTYPE
].
It is as follows:
@namespace svg url(http://www.w3.org/2000/svg);

svg|text, svg|foreignObject {
display: none !important;

:root {
fill: context-fill;
fill-opacity: context-fill-opacity;
stroke: context-stroke;
stroke-opacity: context-stroke-opacity;
stroke-width: context-value;
stroke-dasharray: context-value;
stroke-dashoffset: context-value;
The
context-fill
and
context-stroke
keywords
are as defined in this specification,
where the
context element
for a font glyph
is the corresponding
text content element
The other keywords are as defined in the OpenType specification,
and ensure that the style values from the
text content element
are propagated to the font glyphs,
with appropriate adjustments for the change in the coordinate system
OPENTYPE
].
6.9. Required CSS features
Besides the features described above, the following CSS features must be
also supported in SVG user agents:
in XML documents, external CSS style sheets using the

processing instruction [
xml-stylesheet
@media
@import
and
@charset
rules within style sheets, as defined in CSS 2.1
@font-face
rules
within style sheets [
css-fonts-3
all pseudo-classes defined in CSS 2.1 (including :hover, :link, :active, :visited, :focus, :first-child and :lang)
the ::first-letter and ::first-line pseudo-elements defined in CSS 2.1 (on
text
elements)
6.10. DOM interfaces
6.10.1. Interface SVGStyleElement
An
SVGStyleElement
object represents a
style
element
in the DOM.
Exposed
=Window]
interface
SVGStyleElement
SVGElement
attribute DOMString
type
attribute DOMString
media
attribute DOMString
title
attribute boolean
disabled
};
SVGStyleElement
includes
LinkStyle
The
type
media
and
title
IDL attributes
reflect
the
type
media
and
title
content attributes, respectively.
Chapter 7: Geometry Properties
Beside SVG's styling properties, SVG also defines
geometry properties
. Geometry properties
describe the position and dimension of the
graphics element
circle
ellipse
rect
image
foreignObject
and the
svg
element.
7.1. Horizontal center coordinate: The
cx
’ property
Name:
cx
Value:

Initial:
Applies to:
circle
and
ellipse
elements
Inherited:
no
Percentages:
refer to the width of the current SVG viewport (see
Units
Media:
visual
Computed value:
an absolute length or percentage
Animation type
by computed value
The
cx
property describes the horizontal center coordinate
of the position of the element.
7.2. Vertical center coordinate: The ‘
cy
property
Name:
cy
Value:

Initial:
Applies to:
circle
and
ellipse
elements
Inherited:
no
Percentages:
refer to the height of the current SVG viewport (see
Units
Media:
visual
Computed value:
an absolute length or percentage
Animation type
by computed value
The
cy
property describes the vertical center coordinate
of the position of the element.
7.3. Radius: The ‘
’ property
Name:
Value:

Initial:
Applies to:
circle
element
Inherited:
no
Percentages:
refer to the normalized diagonal of the current SVG viewport (see
Units
Media:
visual
Computed value:
an absolute length or percentage
Animation type
by computed value
The
property describes the radius of the
circle
element.
A negative value for
is
invalid
and must be
ignored
7.4. Horizontal radius: The ‘
rx
property
Name:
rx
Value:

| auto
Initial:
auto
Applies to:
ellipse
rect
elements
Inherited:
no
Percentages:
refer to the width of the current SVG viewport (see
Units
Media:
visual
Computed value:
an absolute length or percentage
Animation type
by computed value
The
rx
property describes the horizontal radius of the
ellipse
element and the curve radius of the
rect
element.
When the computed value of ‘
rx
’ is
auto
, the used radius is equal to the absolute length used for
ry
, creating a circular arc.
If both ‘
rx
’ and ‘
ry
’ have a computed value of
auto
, the used value is 0.
Regardless of how the value is calculated, the used value of ‘
rx
’ for a
rect
is never more than 50% of the used value of
width
for the same shape.
The
auto
behavior is new in SVG 2 for
ellipse
matching the behavior for
rect
elements when
rx
was not specified.
A negative value for
rx
is
invalid
and must be
ignored
7.5. Vertical radius: The ‘
ry
property
Name:
ry
Value:

| auto
Initial:
auto
Applies to:
ellipse
rect
Inherited:
no
Percentages:
refer to the height of the current SVG viewport (see
Units
Media:
visual
Computed value:
an absolute length or percentage
Animatable type:
by computed value
The
ry
property describes the vertical radius of the
ellipse
element and the vertical curve radius of the
rect
element.
When the computed value of ‘
ry
’ is
auto
, the used radius is equal to the absolute length used for
rx
, creating a circular arc.
If both ‘
rx
’ and ‘
ry
’ have a computed value of
auto
, the used value is 0.
Regardless of how the value is calculated, the used value of ‘
ry
’ for a
rect
is never more than 50% of the used value of
height
for the same shape.
The
auto
behavior is new in SVG 2 for
ellipse
matching the behavior for
rect
elements when
ry
was not specified.
A negative value for
ry
is
invalid
and must be
ignored
7.6. Horizontal coordinate: The ‘
’ property
Name:
Value:

Initial:
Applies to:
svg
rect
image
foreignObject
elements
Inherited:
no
Percentages:
refer to the width of the current SVG viewport (see
Units
Media:
visual
Computed value:
an absolute length or percentage
Animation type
by computed value
The
property describes the horizontal coordinate of
the position of the element.
7.7. Vertical coordinate: The ‘
property
Name:
Value:

Initial:
Applies to:
svg
rect
image
foreignObject
elements
Inherited:
no
Percentages:
refer to the height of the current SVG viewport (see
Units
Media:
visual
Computed value:
an absolute length or percentage
Animation type
by computed value
The
property describes the vertical coordinate of
the position of the element.
7.8. Sizing properties: the effect of the
width
’ and ‘
height
properties
See the CSS 2.1 specification for the definitions of
width
and
height
The CSS
width
and
height
properties are used for
sizing some SVG elements. Specifically, they are used to size
rect
svg
image
and
foreignObject
. All of these elements have
‘width’
and
‘height’
presentation attributes.
The properties are also used for laying out embedded elements from the HTML namespace.
The used value of
width
may be constrained by the value of the
max-width
and
min-width
properties.
The used value of
height
may be constrained by the value of the
max-height
and
min-height
properties.
The value
auto
for
width
and
height
on the
svg
element is treated as 100%.
The value
auto
for
width
and
height
on the
image
element is calculated from the referenced image's intrinsic dimensions and aspect ratio, according to the CSS
Default Sizing Algorithm
New in SVG 2. Images embedded in SVG can now be auto-sized to the intrinsic size, or scaled to a fixed height or width according to the intrinsic aspect ratio. This matches the behavior of embedded images in HTML.
The value
auto
for
width
and
height
on other elements is treated as 0.
This means that, for example, a
foreignObject
object element will not shrink-wrap to its contents if
auto
is used.
Chapter 8: Coordinate Systems, Transformations and Units
8.1. Introduction
All SVG content is drawn inside
SVG viewports
Every SVG viewport defines a drawing region characterized by a size
(width, height), and an origin, measured in abstract
user units
Note that the term SVG viewport is distinct from the
"viewport"
term used in CSS.
The
initial viewport
is a top-level
SVG viewport that establishes a mapping between the coordinate system used
by the containing environment (for example, CSS pixels in web browsers)
and
user units
. Establishing an initial viewport is described in more
detail in
The initial viewport
SVG viewports are only established by elements. See
Establishing a new SVG viewport
for information
on which elements generate viewports.
Each SVG viewport generates a
viewport coordinate system
and a
user coordinate system
, initially identical.
Providing a
viewBox
on a viewport's element transforms the user coordinate system
relative to the viewport coordinate system as described in
The
viewBox
attribute. Child elements of a viewport can
further modify the
user coordinate system
, for example by specifying
the
transform
property.
SVG viewports can be nested. Percentage units are resolved with reference
to the user coordinate system of the nearest ancestral viewport-defining element,
as defined in
the section on Units
Hence, nesting
SVG viewports provides an opportunity to redefine the meaning of percentage
units and provide a new reference rectangle for "fitting" a graphic relative
to a particular rectangular area. The
furthest ancestral SVG viewport
is the top most root SVG viewport with
out leaving the
SVG context
. An ancestor SVG viewport might not be
independent of the DOM tree order. E.g. for
linearGradient
radialGradient
pattern
mask
clipPath
symbol
or
use
elements.
An
SVG
context
is a document fragment where all elements within the fragment
have the
SVGElement
as prototype.
The width, height and origin of SVG viewports is established by a negotiation
process between the SVG document fragment generating the SVG viewport, and the
parent of that fragment (whether real or implicit). See
Establishing a new SVG viewport
for a
description of this negotiation process.
By default, a nested SVG viewport's
viewport coordinate system
is equivalent to the local
coordinate system of the parent element, translated by the origin of the SVG viewport's
element. However, a
transform
property on an SVG viewport's element will modify
the
viewport coordinate system
relative to the parent element's user coordinate system.
Abstractly, all SVG viewports are embedded in the
canvas
a drawing region that is infinitely large in all relevant dimensions.
8.2. Computing the equivalent transform of an SVG viewport
This process converts the min-x, min-y, width and height values of a viewBox attribute,
the position and size of the element on which the viewBox attribute is defined,
and the value of the preserveAspectRatio attribute on that element into a translation and
a scale that is applied to content contained by the element.
Let
vb-x
vb-y
vb-width
vb-height
be
the min-x, min-y, width and height values of the viewBox attribute respectively.
Let
e-x
e-y
e-width
e-height
be
the position and size of the element respectively.
Let
align
be the align value of preserveAspectRatio, or 'xMidYMid' if
preserveAspectRatio is not defined.
Let
meetOrSlice
be the meetOrSlice value of preserveAspectRatio, or 'meet'
if preserveAspectRatio is not defined or if meetOrSlice is missing from this value.
Initialize
scale-x
to
e-width
vb-width
Initialize
scale-y
to
e-height
vb-height
If
align
is not 'none' and
meetOrSlice
is 'meet', set
the larger of
scale-x
and
scale-y
to the smaller.
Otherwise, if
align
is not 'none' and
meetOrSlice
is 'slice',
set the smaller of
scale-x
and
scale-y
to the larger.
Initialize
translate-x
to
e-x
- (
vb-x
* scale-x).
Initialize
translate-y
to
e-y
- (
vb-y
* scale-y)
If
align
contains 'xMid', add
e-width
vb-width
scale-x
) / 2 to
translate-x
If
align
contains 'xMax', add
e-width
vb-width
scale-x
) to
translate-x
If
align
contains 'yMid', add
e-height
vb-height
scale-y
) / 2 to
translate-y
If
align
contains 'yMax', add
e-height
vb-height
scale-y
) to
translate-y.
The transform applied to content contained by the element is given by
translate(
translate-x
translate-y
) scale(
scale-x
scale-y
).
8.3. The initial viewport
The initial viewport's width, must be the value of the
width
presentation attribute on the
outermost svg element
, unless the
following conditions are met:
the SVG content is a separately stored resource that is
embedded by reference (such as the
‘object’
element in HTML), or the SVG
content is embedded inline within a containing document;
and the referencing element or containing document is
styled using CSS [
CSS2
];
and there are
CSS-compatible positioning properties
([
CSS2
], section 9.3)
specified on the referencing element (e.g.,
the
‘object’
element) or on
the containing document's
outermost svg element
that are sufficient
to establish the width of the viewport.
Under these conditions, the viewport's width must be established via the
positioning properties.
Similarly, if there are
positioning properties
specified on the referencing element or on the
outermost svg element
that are
sufficient to establish the height of the viewport, then these
positioning properties must establish the viewport's height;
otherwise, the initial viewport's height must be the value of the
height
presentation attribute on the
outermost svg element
If the
width
or
height
presentation attributes on the
outermost svg element
are in
user units
(i.e., no unit
identifier has been provided), then the value is assumed to be
equivalent to the same number of "px" units (see
Units
).
In the following example, an SVG graphic is embedded inline
within a parent XML document which is formatted using CSS
layout rules. Since CSS positioning properties are not provided
on the
outermost svg element
the
width="100px"
and
height="200px"
attributes
determine the size of the initial viewport:

8.4. The initial coordinate system
For the
outermost svg element
, the SVG user
agent must determine an initial
viewport coordinate system
and an
initial
user coordinate system
such that the
two coordinates systems are identical. The origin of both
coordinate systems must be at the origin of the SVG viewport, and one
unit in the initial coordinate system must equal one
CSS 2.1 px
([
CSS2
], section 4.3.2)
in the SVG viewport.

In stand-alone SVG documents and in SVG document fragments embedded
(by reference or inline) within parent documents where the parent's
layout is determined by CSS [
CSS2
],
the initial viewport
coordinate system (and therefore the initial user coordinate
system) must have its origin at the top/left of the viewport, with
the positive x-axis pointing towards the right, the positive
y-axis pointing down, and text rendered with an "upright"
orientation, which means glyphs are oriented such that Roman
characters and full-size ideographic characters for Asian
scripts have the top edge of the corresponding glyphs oriented
upwards and the right edge of the corresponding glyphs oriented
to the right.
If the SVG implementation is part of a user agent which
supports styling documents using CSS 2.1 compatible
px
units, then the SVG user agent should set its
initial value for the size of a
px
unit in real world
units to match the value used for other styling operations;
otherwise, if the user agent can determine the size of a
px
unit from its environment, it should use that
value; otherwise, it should choose an appropriate size for one
px
unit. In all cases, the size of a
px
must
be in conformance with
the rules described in CSS 2.1
([
CSS2
], section 4.3.2).
Example InitialCoords
below
shows that the initial coordinate system has the origin at the
top/left with the x-axis pointing to the right and the y-axis
pointing down. The initial user coordinate system has one user
unit equal to the parent (implicit or explicit) user agent's
"pixel".


Example InitialCoords - SVG's initial coordinate system

(0,0)
(300,0)
(0,100)


Example InitialCoords
View this example as SVG (SVG-enabled browsers only)
8.5. The ‘
transform
’ property
User agents must support the
transform
property and presentation attribute
as defined in [
css-transforms-1
].
8.6. The
‘viewBox’
attribute
Name
Value
Initial value
Animatable
viewBox

,?

,?

,?

As if not specified.
yes
, , , =

Transform on the
svg
element is a bit special due to the
viewBox
attribute. The transform should be applied as if the
svg
had a parent element with that transform set.
RESOLUTION: transform property applies conceptually to the outside of the 'svg' element and there is no difference between
presentation attribute and style property
(in terms of the visual result).
The
viewBox
attribute, in conjunction with the
preserveAspectRatio
attribute, provides the capability to
stretch an SVG viewport to fit a particular container element.
The value of the
viewBox
attribute is a list of four
numbers



and

, separated by
whitespace and/or a comma, that specify a rectangle in user
space that should be mapped to the bounds of the SVG viewport
established by the given element, taking into account the
preserveAspectRatio
attribute.
The presence of the
viewBox
attribute results in a transformation
being applied to the viewport coordinate system as described in
Computing the equivalent transform of an SVG viewport
A negative value for

or

is an error and invalidates
the
viewBox
attribute. A value of zero disables rendering of the
element.
Example ViewBox
illustrates
the use of the
viewBox
attribute
on the
outermost svg element
to specify that
the SVG content should stretch to fit bounds of the
SVG viewport.


xmlns="http://www.w3.org/2000/svg">
Example ViewBox - uses the viewBox
attribute to automatically create an initial user coordinate
system which causes the graphic to scale to fit into the
SVG viewport no matter what size the SVG viewport is.

fill="yellow" stroke="blue" stroke-width="12" />




Stretch to fit


Example ViewBox
Rendered into
SVG viewport with
width=300px,
height=200px
Rendered into
SVG viewport with
width=150px,
height=200px
View
this example as SVG (SVG-enabled browsers only)
The effect of the
viewBox
attribute is that the user agent automatically supplies the
appropriate transformation matrix to map the specified
rectangle in user coordinate system to the bounds of a designated region
(often, the SVG viewport). To achieve the effect of the example on
the left, with SVG viewport dimensions of 300 by 200 pixels, the
user agent needs to automatically insert a transformation which
scales both X and Y by 0.2. The effect is equivalent to having
an SVG viewport of size 300px by 200px and the following
supplemental transformation in the document, as follows:






To achieve the effect of the example on the right, with
SVG viewport dimensions of 150 by 200 pixels, the user agent needs
to automatically insert a transformation which scales X by 0.1
and Y by 0.2. The effect is equivalent to having an SVG viewport of
size 150px by 200px and the following supplemental
transformation in the document, as follows:






Note that in some cases the user agent will need to supply a
translate
transformation in addition to a
scale
transformation. For example, on an
outermost svg element
, a
translate
transformation will be needed if the
viewBox
attributes specifies
values other than zero for

or

If both
transform
(or
patternTransform
and
viewBox
are applied to an element two new coordinate
systems are established.
transform
establishes the first new
coordinate system for the element.
viewBox
establishes a second coordinate system for all descendants of
the element. The first coordinate system is post-multiplied by the
second coordinate system.
Unlike the
transform
property,
the automatic transformation that is created
due to a
viewBox
does not affect
the
‘x’
‘y’
‘width’
and
‘height’
attributes (or in the case of
the
marker
element, the
markerWidth
and
markerHeight
attributes) on the
element with the
viewBox
attribute. Thus, in the example above which shows an
svg
element which has
width
and
height
presentation attributes
and a
viewBox
attribute,
the
width
and
height
represent values in the coordinate system that exists
before
the
viewBox
transformation is applied. On
the other hand, like the
transform
property, it does
establish a new coordinate system for all other attributes and
for descendant elements.
8.7. The
‘preserveAspectRatio’
attribute
Name
Value
Initial value
Animatable
preserveAspectRatio


xMidYMid meet
yes
=
none
| xMinYMin | xMidYMin | xMaxYMin
| xMinYMid | xMidYMid | xMaxYMid
| xMinYMax | xMidYMax | xMaxYMax
= meet | slice
Indicates whether or not to force uniform scaling. Applies to all
elements that establish a new SVG viewport (see
elements that
establish SVG viewports
), plus the
image
marker
pattern
and
view
elements
In some cases, typically when using the
viewBox
attribute, it is desirable that the graphics stretch to
fit non-uniformly to take up the
entire SVG viewport. In other cases, it is desirable that uniform
scaling be used for the purposes of preserving the aspect ratio
of the graphics.
For elements that establish a new SVG viewport (see
elements that
establish SVG viewports
), plus the
marker
pattern
and
view
elements,
preserveAspectRatio
only applies when
a value has been provided for
viewBox
on the same element. For these elements, if attribute
viewBox
is not provided, then
preserveAspectRatio
is ignored.
For
image
elements,
preserveAspectRatio
indicates how
referenced images should be fitted with respect to the
reference rectangle and whether the aspect ratio of the
referenced image should be preserved with respect to the
current user coordinate system.
The

parameter
indicates whether to force uniform scaling and, if so, the
alignment method to use in case the aspect ratio of the
viewBox
doesn't match the aspect ratio of the SVG viewport. The

parameter must be one
of the following strings:
none
- Do not force
uniform scaling. Scale the graphic content of the given
element non-uniformly if necessary such that the element's
bounding box exactly matches the SVG viewport rectangle.
(Note: if

is
none
, then the optional

value is
ignored.)
xMinYMin
- Force uniform
scaling.
Align the

of
the element's
viewBox
with the smallest X
value of the SVG viewport.
Align the

of
the element's
viewBox
with the smallest Y
value of the SVG viewport.
xMidYMin
- Force uniform
scaling.
Align the midpoint X value of the element's
viewBox
with the midpoint X value of the SVG viewport.
Align the

of
the element's
viewBox
with the smallest Y
value of the SVG viewport.
xMaxYMin
- Force uniform
scaling.
Align the
+
of the
element's
viewBox
with the maximum X value
of the SVG viewport.
Align the

of
the element's
viewBox
with the smallest Y
value of the SVG viewport.
xMinYMid
- Force uniform
scaling.
Align the

of
the element's
viewBox
with the smallest X
value of the SVG viewport.
Align the midpoint Y value of the element's
viewBox
with the midpoint Y
value of the SVG viewport.
xMidYMid
(the
initial value
) -
Force uniform scaling.
Align the midpoint X value of the element's
viewBox
with the midpoint X value of the SVG viewport.
Align the midpoint Y value of the element's
viewBox
with the midpoint Y value of the SVG viewport.
xMaxYMid
- Force uniform
scaling.
Align the
+
of the
element's
viewBox
with the maximum X value of the SVG viewport.
Align the midpoint Y value of the element's
viewBox
with the midpoint Y
value of the SVG viewport.
xMinYMax
- Force uniform
scaling.
Align the

of
the element's
viewBox
with the smallest X
value of the SVG viewport.
Align the
+
of the
element's
viewBox
with the maximum Y value
of the SVG viewport.
xMidYMax
- Force uniform
scaling.
Align the midpoint X value of the element's
viewBox
with the midpoint X value of the SVG viewport.
Align the
+
of the
element's
viewBox
with the maximum Y value
of the SVG viewport.
xMaxYMax
- Force uniform
scaling.
Align the
+
of the
element's
viewBox
with the maximum X value
of the SVG viewport.
Align the
+
of the
element's
viewBox
with the maximum Y value
of the SVG viewport.
The

parameter is optional and, if provided, is separated from the

value by one or
more spaces and then must be one of the following strings:
meet
(the default) - Scale
the graphic such that:
aspect ratio is preserved
the entire
viewBox
is visible within
the SVG viewport
the
viewBox
is scaled up as much
as possible, while still meeting the other criteria
In this case, if the aspect ratio of the graphic does not
match the SVG viewport, some of the SVG viewport will extend beyond
the bounds of the
viewBox
(i.e., the area into
which the
viewBox
will draw will be
smaller than the SVG viewport).
slice
- Scale the graphic
such that:
aspect ratio is preserved
the entire SVG viewport is covered by the
viewBox
the
viewBox
is scaled down as
much as possible, while still meeting the other
criteria
In this case, if the aspect ratio of the
viewBox
does not match the
SVG viewport, some of the
viewBox
will extend beyond the
bounds of the SVG viewport (i.e., the area into which the
viewBox
will draw is larger
than the SVG viewport).
Example PreserveAspectRatio
illustrates the various options on
preserveAspectRatio
The example creates several new SVG viewports by
including
svg
sub-elements embedded
inside the
outermost svg element
(see
Establishing a new
SVG viewport
).


Example PreserveAspectRatio - illustrates preserveAspectRatio attribute

SVG to fit

Viewport 1

Viewport 2

--------------- meet ---------------

xMin*






xMid*






xMax*

---------- meet ----------

*YMin






*YMid






*YMax

---------- slice ----------

xMin*






xMid*






xMax*

--------------- slice ---------------

*YMin






*YMid






*YMax







Example PreserveAspectRatio
8.8. Establishing a new SVG viewport
Including an
svg
element inside SVG content
creates a new SVG viewport into which all contained
graphics are drawn; this implicitly establishes both
a new viewport coordinate system and a new user coordinate system.
Additionally, there is a new meaning for percentage units therein,
because a new SVG viewport has been established
(see
Units
).
The bounds of the new SVG viewport are defined by the
‘x’
‘y’
‘width’
and
‘height’
attributes on the element
establishing the new SVG viewport, such as an
svg
element. Both the new
viewport coordinate system and the new user coordinate system
have their origins at (
‘x’
‘y’
), where
‘x’
and
‘y’
represent the value of the corresponding attributes on the
element establishing the SVG viewport. The orientation of the new
viewport coordinate system and the new user coordinate system
correspond to the orientation of the current user coordinate
system for the element establishing the SVG viewport. A single unit
in the new viewport coordinate system and the new user
coordinate system are the same size as a single unit in the
current user coordinate system for the element establishing the SVG
viewport.
Here is an example:


This SVG drawing embeds another one,
thus establishing a new SVG viewport






For an extensive example of creating new SVG viewports, see
Example
PreserveAspectRatio
The following elements establish new SVG viewports:
The
svg
element
symbol
element
that is instanced by a
use
element.
For historical reasons,
the
pattern
and
marker
elements
do not create a new viewport,
despite accepting a
viewBox
attribute.
Neither do the
clipPath
or
mask
elements.
Percentage lengths within the content of these elements
are not proportional to the dimensions of the graphical effect region.
The
foreignObject
element establishes a new
CSS containing block
for its child content.
This has some effects similar to a new viewport,
resetting the scope of layout for child content.
However, in order to render SVG elements that are descendents of
foreignObject
a new
svg
element must establish an SVG document fragment and SVG viewport.
An
image
creates a new
document viewport
for the referenced document.
If the referenced document is a SVG file, it will of course establish its own SVG viewport.
Whether a new SVG viewport also establishes a new additional
clipping path is determined by the value of the
overflow
property on the element
that establishes the new SVG viewport.
8.9. Units
SVG follows the description and definition of common values and
units from the CSS Values and Units Module
css-values
] for attributes,
presentation attributes and CSS properties. Each attribute and property
must specify the used component value type. Subsequent or extending
specifications published by the CSS WG or SVG WG may extend basic data
types or add new data types.
For

values that are defined to be relative
to the size of SVG viewport:
For any x-coordinate value or width value expressed as a percentage of the
SVG viewport
, the value to use must be the percentage, in user
units, of the width parameter of the
viewBox
applied to that viewport.
If no
viewBox
is specified, then the value to use must be the percentage, in
user units, of the width of the
SVG viewport
For any y-coordinate value or height value expressed as a percentage of the
SVG viewport
, the value to use must be the percentage, in user
units, of the height parameter of the
viewBox
applied to that viewport.
If no
viewBox
is specified, then the value to use must be the percentage, in
user units, of the height of the
SVG viewport
For any other length value expressed as a
percentage of the
SVG viewport
, the percentage must be calculated as a
percentage of the normalized diagonal of the
viewBox
applied to that viewport.
If no
viewBox
is specified, then the normalized diagonal of the
SVG viewport
must be used. The normalized diagonal length must be calculated with
sqrt((
width
)**2 + (
height
)**2)/sqrt(2)
Example Units
below
illustrates some of the processing rules for different types of
units.



Illustrates various units options

fill="none" stroke="blue" stroke-width="10"/>

Abs. units:

Rel. units:

Percentages:








Example Units
The three rectangles on the left demonstrate the use of one
of the absolute unit identifiers, the "in" unit (inch). CSS defines 1
inch to be equal to 96 pixels. Therefore, the topmost rectangle, which is
specified in inches, is exactly the same size as the middle
rectangle, which is specified in user units such that there are
96 user units for each corresponding inch in the topmost
rectangle. The bottom rectangle of the group illustrates
what happens when values specified in inches are scaled.
The three rectangles in the middle demonstrate the use of
one of the relative unit identifiers, the "em" unit. Because
the
font-size
property has been set
to
150
on the outermost
element, each "em" unit is
equal to 150 user units. The topmost rectangle, which is
specified in "em" units, is exactly the same size as the middle
rectangle, which is specified in user units such that there are
150 user units for each corresponding "em" unit in the topmost
rectangle. The bottom rectangle of the group illustrates what
happens when values specified in "em" units are scaled.
The three rectangles on the right demonstrate the use of
percentages. Note that the width and height of the SVG viewport in
the user coordinate system for the SVG viewport element (in this
case, the
outermost svg element
) are 4000 and
2000, respectively, because processing the
viewBox
attribute results in a
transformed user coordinate system. The topmost rectangle,
which is specified in percentage units, is exactly the same
size as the middle rectangle, which is specified in equivalent
user units. In particular, note that the
stroke-width
property in the
middle rectangle is set to 1% of the
sqrt((
actual-width
)**2 +
actual-height
)**2) / sqrt(2)
, which in this
case is .01*sqrt(4000*4000+2000*2000)/sqrt(2), or 31.62. The
bottom rectangle of the group illustrates what happens when
values specified in percentage units are scaled.
8.10. Bounding boxes
bounding box
The bounding box (or "bbox") of an element is the tightest fitting rectangle
aligned with the axes of that element's user coordinate system that entirely
encloses it and its descendants.
Three kinds of bounding boxes can be computed for an element:
The
object bounding box
is the bounding box that contains only
an element's geometric shape. For
basic shapes
, this is the area
that is filled. Unless otherwise specified, this is what is meant by the
unqualified term "bounding box".
The
stroke bounding box
is the bounding box that contains
an element's geometric shape and its
stroke shape
The
decorated bounding box
is the bounding box that contains
an element's geometric shape, its
stroke shape
and its
markers
Note that the values of the
opacity
visibility
fill
fill-opacity
fill-rule
stroke-dasharray
and
stroke-dashoffset
properties on an element have no effect on the
bounding box of an element.
For curved shapes, the bounding box must enclose all portions of the shape
along the edge, not just end points. Note that control points for a curve which
are not defined as lying along the line of the resulting curve (e.g., the second
coordinate pair of a Cubic Bézier command) must not contribute to the dimensions
of the bounding box (though those points may fall within the area of the
bounding box, if they lie within the shape itself, or along or close to the
curve). For example, control points of a curve that are at a further distance
than the curve edge, from the non-enclosing side of the curve edge, must be
excluded from the bounding box.
The path
'M20,50 L35,100 H120 V50 Q70,10 20,50'
is shown in light blue. On the left, a correct object bounding box of the path is
shown. Note that it does not include the top-most control point of the curve, but
it does include all of the blue shape, even the parts that lie outside of the convex hull
of the control points.
Even if an element is not in the
rendering tree
– due to it being
'display: none'
, within a
defs
element, not usually rendered like a
symbol
element or not
currently present in the document tree – it still has a bounding box.
A call to
getBBox
on the element will return the same rectangle as if the element were
rendered. However, an element that is not in the
rendering tree
does not contribute to the bounding box of any ancestor element.
The following example defines a number of elements. The expected
object bounding box
for each element with an ID is shown below.

Examples of elements with different bounding box results based on context.

Element ID
Bounding Box Result
defs-1
{0, 0, 0, 0}
rect-1
{20, 20, 40, 40}
group-1
{30, 30, 40, 40}
use-1
{30, 30, 40, 40}
group-2
{10, 10, 100, 100}
rect-2
{10, 10, 100, 100}
For
text content elements
, for the purposes of the bounding box
calculation, each glyph must be treated as a separate graphics element.
The calculations must assume that all glyphs occupy the
full glyph cell
The
full glyph cell
must have width
equal to the horizontal advance and height equal to the EM box for horizontal
text. For vertical text that is typeset sideways, the
full glyph cell
must
have width equal to the EM box and height equal to the horizontal advance.
For other vertical text, the
full glyph cell
must have width equal to the
EM box and height equal to the vertical advance, or height equal to the height
of the EM box if no vertical advance is defined in the font.
For example, for horizontal text, the calculations must assume that each glyph
extends vertically to the full ascent and descent values for the font.
Because declarative or scripted animation can change the shape, size, and
position of an element, the bounding box is mutable. Thus, the bounding box
for an element shall reflect the current values for the element at the snapshot
in time at which the bounding box is requested, whether through a script call
or as part of a declarative or linking syntax.
An element which has zero width, zero height, or both (such as a
vertical or horizontal line, or a
rect
element with a zero
width
or
height
) still has a bounding box, with a
positive value for the positive dimension, or with
'0'
for both the width and height if no positive dimension is specified. Similarly,
subpaths segments of a
path
element with zero width and height must be
included in that element's geometry for the sake of the bounding box.
An element with no position specified (such as a
path
element with a value of
none
for the
property) is positioned at the
point (0,0) for the purposes of calculating a bounding box.
Note that elements whose DOM object does not derive from
SVGGraphicsElement
(such as gradient elements) do not have a bounding box, and thus have no
interface to request a bounding box.
Elements in the
rendering tree
which reference unresolved resources shall
still have a bounding box, defined by the position and dimensions specified in
their attributes, or by the
initial value
for those attributes if no
values are supplied. For example, the element

would have a bounding box with an x and y of 10 and a width and height of 0.
The following algorithm defines how to compute a bounding box for a given
element. The inputs to the algorithm are:
element
, the element we are computing a bounding box for;
space
, a coordinate space in which the bounding box will be computed;
fill
, a boolean indicating whether the bounding box includes the geometry of the element and its descendants;
stroke
, a boolean indicating whether the bounding box includes the stroke of the element and its descendants;
markers
, a boolean indicating whether the bounding box includes the markers of the element and its descendants; and
clipped
, a boolean indicating whether the bounding box is affected by any clipping paths applied to the element and its descendants.
The algorithm to compute the bounding box is as follows, depending on the type of
element
shape
text content element
an
element within a
text content element
Let
box
be a rectangle initialized to (0, 0, 0, 0).
Let
fill-shape
be the
equivalent path
of
element
if it is a
shape
, or a shape that includes each of the glyph cells corresponding
to the text within the elements otherwise.
If
fill
is true, then set
box
to the tightest rectangle
in the coordinate system
space
that contains
fill-shape
The values of the
fill
fill-opacity
and
fill-rule
properties do not affect
fill-shape
If
stroke
is true and the element's
stroke
is anything other than
none
, then set
box
to be the union of
box
and the
tightest rectangle in coordinate system
space
that contains the
stroke shape
of the
element, with the assumption that the element has no dash pattern.
The values of the
stroke-opacity
stroke-dasharray
and
stroke-dashoffset
do not affect the calculation of the stroke shape.
If
markers
is true, then for each marker
marker
rendered on the element:
For each descendant
graphics element
child
of the
marker
element
that defines
marker
's content:
If
child
has an ancestor element within the
marker
that is
'display: none'
, has a failing
conditional processing attribute
or is not an
svg
or
switch
element, then
continue to the next descendant
graphics element
Otherwise, set
box
to be the union of
box
and the result of invoking the
algorithm to compute a bounding box with
child
as the element,
space
as the target coordinate space, true for
fill
stroke
and
markers
, and
clipped
for
clipped
If
clipped
is true and the value of
clip-path
on
element
is not
none
, then set
box
to be the tightest rectangle
in coordinate system
space
that contains the intersection of
box
and the clipping path.
Return
box
container element
use
Let
box
be a rectangle initialized to (0, 0, 0, 0).
Let
parent
be the
container element
if it is one, or the
root of the
use
element's shadow tree otherwise.
For each descendant
graphics element
child
of
parent
If
child
is
not rendered
then
continue to the next descendant
graphics element
Otherwise, set
box
to be the union of
box
and the result of invoking the
algorithm to compute a bounding box with
child
as the element
and the same values for
space
fill
stroke
markers
and
clipped
as the corresponding algorithm input values.
If
clipped
is true:
If the value of
clip-path
on
element
is not
none
then set
box
to be the tightest rectangle
in coordinate system
space
that contains the intersection of
box
and the clipping path.
If the
overflow
property applies to the
element
and does not have a value of
visible
then set
box
to be the tightest rectangle
in coordinate system
space
that contains the intersection of
box
and the element's overflow bounds.
If the
clip
property applies to the
element
and does not have a value of
auto
then set
box
to be the tightest rectangle
in coordinate system
space
that contains the intersection of
box
and the rectangle specified by
clip
Return
box
foreignObject
image
Let
box
be the tightest rectangle in coordinate space
space
that
contains the
positioning rectangle
defined by the
‘x’
‘y’
‘width’
and
‘height’
geometric properties of the element.
The
fill
stroke
and
markers
input arguments to this algorithm do not affect the bounding box returned
for these elements.
If
clipped
is true and the value of
clip-path
on
element
is not
none
, then set
box
to be the tightest rectangle
in coordinate system
space
that contains the intersection of
box
and the clipping path.
Return
box
The union
box
with a value of (0, 0, 0, 0) and an empty shape
is
box
The
object bounding box
stroke bounding box
or
decorated bounding box
of an element is the result of invoking the bounding box computation algorithm
above with the following arguments:
element
is the element itself;
space
is the element's user coordinate system;
fill
is true;
stroke
is true if we are computing the
stroke bounding box
or
decorated bounding box
, and false otherwise;
markers
is true if we are computing the
decorated bounding box
, and false otherwise; and
clipped
is false.
8.11. Object bounding box units
The following elements offer the option of expressing
coordinate values and lengths as fractions (and, in some cases,
percentages) of the
object bounding box
by setting a specified attribute to
'objectBoundingBox'
on the given element:
Element
Attribute
Effect
linearGradient
gradientUnits
Indicates that the attributes which specify the
gradient vector (
x1
y1
x2
y2
) represent fractions or
percentages of the bounding box of the element to which the
gradient is applied.
radialGradient
gradientUnits
Indicates that the attributes which specify the center
cx
cy
), the radius (
) and focus
fx
fy
) represent fractions or
percentages of the bounding box of the element to which the
gradient is applied.
pattern
patternUnits
Indicates that the attributes which define how to tile the pattern
width
height
) are
established using the bounding box of the element to which the pattern
is applied.
pattern
patternContentUnits
Indicates that the user coordinate system for the
contents of the pattern is established using the bounding
box of the element to which the pattern is applied.
clipPath
clipPathUnits
Indicates that the user coordinate system for the contents of the
clipPath
element is established using the bounding box of the
element to which the clipping path is applied.
mask
maskUnits
Indicates that the attributes which define the masking region
width
height
) is
established using the bounding box of the element to which the mask
is applied.
mask
maskContentUnits
Indicates that the user coordinate system for the contents of
the
mask
element are established using the bounding box of
the element to which the mask is applied.
filter
filterUnits
Indicates that the attributes which define the
filter effects region
width
height
) represent
fractions or percentages of the bounding box of the element to which
the filter is applied.
filter
primitiveUnits
Indicates that the various length values within the filter
primitives represent fractions or percentages of the bounding box of
the element to which the filter is applied.
In the discussion that follows, the term
applicable element
is the element to which the given effect applies. For gradients and
patterns, the applicable element is the
graphics element
which has its
fill
or
stroke
property referencing the
given gradient or pattern. (For special rules concerning
text elements
, see the discussion of
object
bounding box units and text elements
.) For clipping paths,
masks and filters, the applicable element can be either a
container element
or a
graphics element
When keyword
objectBoundingBox
is used, then the
effect is as if a supplemental transformation matrix were
inserted into the list of nested transformation matrices to
create a new user coordinate system.
First, the (
minx
miny
) and
maxx
maxy
) coordinates are
determined by the extends of the
object bounding box
of
the applicable element.
Then, coordinate (0,0) in the new user coordinate system is
mapped to the (minx,miny) corner of the tight bounding box
within the user coordinate system of the applicable element and
coordinate (1,1) in the new user coordinate system is mapped to
the (maxx,maxy) corner of the tight bounding box of the
applicable element. In most situations, the following
transformation matrix produces the correct effect:
[ (maxx-minx) 0 0 (maxy-miny) minx miny ]
When percentages are used with attributes that define the
gradient vector, the pattern tile, the filter region or the
masking region, a percentage represents the same value as the
corresponding decimal value (e.g., 50% means the same as 0.5).
If percentages are used within the content of a
pattern
clipPath
mask
or
filter
element, these values
are treated according to the processing rules for percentages
as defined in
Units
Any numeric value can be specified for values expressed as a
fraction or percentage of object bounding box units. In
particular, fractions less than zero or greater than one and
percentages less than 0% or greater than 100% can be
specified.
Keyword
objectBoundingBox
should not be used when the geometry of the applicable element
has no width or no height, such as the case of a horizontal or
vertical line, even when the line has actual thickness when
viewed due to having a non-zero stroke width since stroke width
is ignored for bounding box calculations. When the geometry of
the applicable element has no width or height and
objectBoundingBox
is specified, then
the given effect (e.g., a gradient or a filter) will be
ignored.
8.12. Intrinsic sizing properties of SVG content
To enable inclusion of SVG in host documents formatted with CSS, a
concrete object size
must be calculated.
The
concrete object size
must be calculated using the
Default Sizing Algorithm
defined in CSS Images 3 [
css-images-3
],
with the following inputs:
The
specified size
must be determined from the used values for the
width
and
height
sizing properties of the
svg
element.
The
intrinsic dimensions
must also be determined from the
width
and
height
sizing properties. If either
width
or
height
are
not specified, the used value is the initial value
'auto'
'auto'
and percentage lengths must not be used to
determine an
intrinsic width
or
intrinsic height
With bitmap image formats, the
intrinsic dimensions
are fixed in
the image file, and the specified size is defined in the host document as needed
to scale the image.
SVG, being inherently scalable, adapts the
intrinsic width
and
intrinsic height
to be the width and height of the
specified size
Therefore, when specified as a length, the
width
and
height
sizing properties of the
svg
element control the
intrinsic dimensions
of the SVG image and the
specified size
that
is used when placing the SVG image in a host document.
The
intrinsic aspect ratio
must be calculated using the following
algorithm. If the algorithm returns null, then there is no intrinsic aspect ratio.
If the
width
and
height
sizing properties on the
svg
element are both absolute values:
return width / height
If an
SVG View
is active:
let
viewbox
be the viewbox defined by the active SVG View
return
viewbox
.width /
viewbox
.height
If the
viewBox
on the
svg
element is correctly specified:
let
viewbox
be the viewbox defined by the
viewBox
attribute on the
svg
element
return
viewbox
.width /
viewbox
.height
return null
The behaviour defined in this section is specific to CSS, but may be adapted
to other host contexts. In all host contexts, the
intrinsic aspect ratio
where available, must be respected when sizing the SVG viewport.
Examples:
Example:
Intrinsic Aspect Ratio 1

...

In this example the intrinsic aspect ratio of the
SVG viewport
is 2:1. The
intrinsic width is 10cm and the intrinsic height is 5cm.
Example:
Intrinsic Aspect Ratio 2

...

In this example the intrinsic aspect ratio of the outermost
SVG viewport
is
1:1. An aspect ratio calculation in this case allows embedding in an
object within a containing block that is only constrained in one direction.
Example:
Intrinsic Aspect Ratio 3

...

In this case the intrinsic aspect ratio is 1:1.
Example:
Intrinsic Aspect Ratio 4

...

In this example, the intrinsic aspect ratio is 1:1.
Add more examples for the new auto value? E.g. some of the
examples
provided by David Vest.
8.13. Vector effects
SVG 2 Requirement:
SVG 2 will have constrained transformations based on SVG 1.2 Tiny.
Resolution:
Add vector effects extension proposal to SVG 2 specification.
Purpose:
To include non-scaling features (non-scaling part of the object, and non-scaling entire object
Owner:
Satoru Takagi (
ACTION-3619
Sometimes it is of interest to let the outline of an object keep its
original width or to let the position of an object fix no matter which
transforms are applied to it. For example, in a map with a 2px wide line
representing roads it is of interest to keep the roads 2px wide even when the
user zooms into the map, or introductory notes on the graphic chart in which
panning is possible.
To offer such effects regarding special coordinate transformations and
graphic drawings, SVG Tiny 1.2 introduced the
vector-effect
property.
Although SVG Tiny 1.2 introduced only non-scaling stroke behavior, this version
introduces a number of additional effects. Furthermore, since these effects
can be specified in combination, they show more various effects. And, future
versions of the SVG language will allow for more powerful vector effects
through this property.
Values of
vector-effect
other than
non-scaling-stroke
and
none
are at risk of being dropped from SVG 2 due to a lack of implementations.
Feedback from implementers is requested,
regarding the practicality of implementing them as currently specified,
during the implementation period.
Name:
vector-effect
Value:
none | non-scaling-stroke | non-scaling-size | non-rotation | fixed-position
Initial:
none
Applies to:
graphics elements
and
use
Inherited:
no
Percentages:
N/A
Media:
visual
Computed value:
as specified
Animation type
discrete
none
Specifies that no vector effect shall be applied, i.e. the default rendering behaviour
from SVG 1.1 is used which is to first fill the geometry of a shape with a specified
paint, then stroke the outline with a specified paint.
non-scaling-stroke
Please refer to
this description
of vector effect on painting.
non-scaling-size
Specifies special
user coordinate system
toward this element
and its descendant by constrained transformations with the following
characteristics. The scale of the
user coordinate system
do not
change in spite of change of
CTM
s from a
host coordinate space
However, it does not specify the suppression of rotation and skew. Also,
it does not specify the fixation of placement of
user coordinate system
Since non-scaling-size suppresses scaling of
user coordinate system
it also has the characteristic of non-scaling-stroke. The transformation
formula and the example behavior are indicated to the following chapter.
non-rotation
Specifies special
user coordinate system
toward this element
and its descendant by constrained transformations with the following
characteristics. The rotation and skew of the
user coordinate system
is suppressed in spite of change of
CTM
s from a
host coordinate space
However, it does not specify the suppression of scaling. Also, it does not
specify the fixation of placement of
user coordinate system
The transformation formula and the example behavior are indicated to the
following chapter.
fixed-position
Specifies special
user coordinate system
toward this element
and its descendant by constrained transformations with the following
characteristics. The placement of
user coordinate system
is fixed
in spite of change of
CTM
s from a
host coordinate space
. However,
it does not specify the suppression of rotation, skew and scaling. When
the element that has fixed-position effect and also has
transform
property, that property is consumed for this effect. The shift components
and
of matrix of
transform
property are
used to transfer the origin of fixed
user coordinate system
. The
transformation formula and the example behavior are indicated to the
following chapter.
These values can be enumerated. Thereby, the effect which has these
characteristics simultaneously can be specified.
The host coordinate space for
vector-effect
is the
viewport coordinate system
of the
furthest ancestral SVG viewport
Note: Future versions of SVG may allow ways to specify the device coordinate system.
8.13.1. Computing the vector effects
This section shows the list of transformation formulas regarding
combinations of the values for clarification of the behavior of vector effects
excluding
non-scaling-stroke
which has clear
implications.
The
vector-effect
property has no effect on transformations
performed in a
3d rendering context
The normal coordinate transformation formula from
user coordinate system
to
viewport coordinate system
is as follows.
viewport
viewport
CTM
userspace
userspace
CTM
ctm
ctm
ctm
ctm
ctm
ctm

When the
vector-effect
is added to an element like the above, the
transformation formula for user coordinate to the device coordinate changes as
follows. Here,
and
are user
coordinate of the corresponding element and its descendant. And,
and
are matrix element
and
of the transform attribute which the
corresponding element has. In addition,
|det(CTM)|
is absolute value of
the determinants of
CTM
. When this value becomes 0 and
non-scaling-size
is appointed,
vector-effect
becomes invalidity namely
none
det
CTM
ctm
ctm
ctm
ctm
veValue
Formula
non-scaling-size
viewport
viewport
CTM
CTM
det
CTM
non-rotation
viewport
viewport
CTM
det
CTM
non-scaling-size
non-rotation
viewport
viewport
CTM
fixed-position
viewport
viewport
CTM
fixed-position
non-scaling-size
viewport
viewport
CTM
det
CTM
fixed-position
non-rotation
viewport
viewport
det
CTM
fixed-position
non-scaling-size
non-rotation
viewport
viewport
8.13.2. Computing the vector effects for nested viewport coordinate systems
Below is normal coordinate transformation formula for nested viewport
coordinate systems without vector effects.
viewport(UA)
and
viewport(UA)
are coordinates which under the immediate
control of
user agent
CTM
this
is
CTM
for the
transformation matrix from
user coordinate system
of an target graphic
to
viewport coordinate system
to which it belongs.
CTM
parent
is
CTM
for the transformation matrix from
aforementioned
viewport coordinate system
to
viewport coordinate system
of the parent of that. And,
CTM
root
is
CTM
for
rootmost viewport coordinate system (UA).
viewport(UA)
viewport(UA)
CTM
root
...
CTM
parent
CTM
this
userspace
userspace
When applying seven formulas of the preceding section to nested viewport
coordinate systems, the application way of those formulas changes as follows
by whether
viewport
or
screen
is specified as the additional value of
vector-effect
When
viewport
value is specified,
user agent
computes coordinates combining either of seven formulas of
the preceding chapter, and the following formulas.
viewport
UA
viewport
UA
CTM
root
...
CTM
parent
viewport
viewport
CTM
CTM
this
When
screen
value is specified,
user agent
computes coordinates combining either of seven formulas of
the preceding chapter, and the following formulas.
viewport
UA
viewport
UA
viewport
viewport
CTM
CTM
root
...
CTM
parent
CTM
this
8.13.3. Examples of vector effects
Below is an example of the
non-scaling-stroke
vector-effect


viewport-fill="rgb(255,150,200)">

Example non-scaling stroke

x1="32" y1="50" x2="32" y2="350"/>
x1="55" y1="50" x2="55" y2="350"/>

Below is an example of the
none
vector-effect
(no vector effect).
Before changing CTM
After changing CTM
Source code

stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>



Below is an example of the
non-scaling-size
Before changing CTM
After changing CTM
stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the
non-rotation
Before changing CTM
After changing CTM
stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the
non-scaling-size
non-rotation
Before changing CTM
After changing CTM
stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the
fixed-position
Before changing CTM
After changing CTM
stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the
non-scaling-size
fixed-position
Before changing CTM
After changing CTM
stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the
non-rotation
fixed-position
Before changing CTM
After changing CTM
stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the
non-scaling-size
non-rotation
fixed-position
Before changing CTM
After changing CTM
stroke="red" stroke-width="3" fill="none"
transform="matrix(1,0,0,1,150,150)"
d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
8.14. DOM interfaces
8.14.1. Interface SVGTransform
The
SVGTransform
interface is used to represent

values that appear in the
transform
property
and its presentation attributes
‘transform’
gradientTransform
and
patternTransform
. An
SVGTransform
represents a single component in a transform list,
such as a single
scale(…)
or
matrix(…)
value.
An
SVGTransform
object can be designated as
read only
which means that attempts to modify the object will result in an exception
being thrown, as described below.
An
SVGTransform
object can be
associated
with a particular element. The associated element is used to
determine which element's
‘transform’
presentation attribute to update if the object
reflects
that attribute. Unless otherwise described, an
SVGTransform
object is
not associated with any element.
Every
SVGTransform
object operates in one of
two modes. It can:
reflect an element of a presentation attribute value
(being exposed through the methods on the
baseVal
member of
an
SVGAnimatedTransformList
),
be detached
, which is the case for
SVGTransform
objects created
with
createSVGTransform
and
createSVGTransformFromMatrix
An
SVGTransform
object maintains an internal

value, which is called its
value
It also maintains a
DOMMatrix
object,
which is called its
matrix object
which is the object returned from the
matrix
IDL attribute. An
SVGTransform
object's
matrix object
is always kept synchronized with its
value
Exposed
=Window]
interface
SVGTransform

// Transform Types
const unsigned short
SVG_TRANSFORM_UNKNOWN
= 0;
const unsigned short
SVG_TRANSFORM_MATRIX
= 1;
const unsigned short
SVG_TRANSFORM_TRANSLATE
= 2;
const unsigned short
SVG_TRANSFORM_SCALE
= 3;
const unsigned short
SVG_TRANSFORM_ROTATE
= 4;
const unsigned short
SVG_TRANSFORM_SKEWX
= 5;
const unsigned short
SVG_TRANSFORM_SKEWY
= 6;

readonly attribute unsigned short
type
SameObject
] readonly attribute
DOMMatrix
matrix
readonly attribute float
angle

undefined
setMatrix
(optional
DOMMatrix2DInit
matrix = {});
undefined
setTranslate
(float tx, float ty);
undefined
setScale
(float sx, float sy);
undefined
setRotate
(float angle, float cx, float cy);
undefined
setSkewX
(float angle);
undefined
setSkewY
(float angle);
};
The numeric transform type constants defined on
SVGTransform
are used
to represent the type of an
SVGTransform
's
value
Their meanings are as follows:
Constant
Meaning
SVG_TRANSFORM_MATRIX
matrix(…)
value.
SVG_TRANSFORM_TRANSLATE
translate(…)
value.
SVG_TRANSFORM_SCALE
scale(…)
value.
SVG_TRANSFORM_ROTATE
rotate(…)
value.
SVG_TRANSFORM_SKEWX
skewX(…)
value.
SVG_TRANSFORM_SKEWY
skewY(…)
value.
SVG_TRANSFORM_UNKNOWN
Some other type of value.
The use of numeric transform type constants is an anti-pattern and
new constant values will not be introduced for any transform types supported by
SVGTransform
. If other types of transforms are supported and used, the
SVGTransform
uses the
SVG_TRANSFORM_UNKNOWN
type. See below for details on how the other properties of an
SVGTransform
operate with these types of transforms.
The
type
IDL attribute represents
the type of transform item that the
SVGTransform
's
value
is.
On getting
type
, the following steps
are run:
If the
SVGTransform
's
value
is a
matrix(…)
translate(…)
scale(…)
rotate(…)
skewX(…)
or
skewY(…)
function,
then return the corresponding constant
value from the transform type table above.
Otherwise, return
SVG_TRANSFORM_UNKNOWN
For example, for a
scaleX(…)
or
translate3d(…)
transform,
SVG_TRANSFORM_UNKNOWN
would be returned.
The
matrix
IDL attribute
represents the transform as a 4x4 homogeneous matrix, and on getting
returns the
SVGTransform
's
matrix object
When the
matrix object
is first created, its
values are set to match the
SVGTransform
's transform
function
value
, and is set to
reflects the SVGTransform
See the
CSS Transforms
specification for a description of how the different transform function types
correspond to particular matrix values.
The
angle
IDL attribute
represents the angle parameter of a
rotate(…)
skewX(…)
or
skewY(…)
transform function.
On getting, the following steps are run:
If the
SVGTransform
object's
value
is a
rotate(…)
skewX(…)
or
skewY(…)
function,
return its angle argument in degrees.
Otherwise, return 0.
The
setMatrix
method is used
to set the
SVGTransform
to a given matrix value. When
setMatrix(
matrix
) is called, the following steps are run:
If the
SVGTransform
object is
read only
, then
throw
NoModificationAllowedError
Let
newMatrix
be the result of
DOMMatrixReadOnly
.fromMatrix(
matrix
including the
validate and fix-up
steps for missing values.
If that method throws an error, then re-throw that error and abort these steps.
If
newMatrix
.is2D() would return true,
then set the
SVGTransform
object's
value
to a
matrix(…)
value that represents the same matrix as
newMatrix
Otherwise, set the
SVGTransform
object's
value
to a
matrix3d(…)
value that represents the same matrix as
newMatrix
In either case,
matrix object
gets synchronized
to the
SVGTransform
object's
value
If the
SVGTransform
object
reflects a presentation attribute value of an element
then
reserialize
the reflected attribute.
The
setTranslate
setScale
setRotate
setSkewX
and
setSkewY
methods are used
to set the
SVGTransform
to a new transform function
value. When one of these methods is called,
the following steps are run:
If the
SVGTransform
object is
read only
, then
throw
NoModificationAllowedError
Set the
SVGTransform
object's
value
to a new transform function
value, depending on which method was called:
setTranslate(
tx
ty
the new transform function value is
translate(
tx
ty
setScale(
sx
sy
the new transform function value is
scale(
sx
sy
setRotate(
angle
cx
cy
the new transform function value is
rotate(
angle
cx
cy
setSkewX(
angle
the new transform function value is
skewX(
angle
setSkewY(
angle
the new transform function value is
skewY(
angle
Set the components of the
SVGTransform
object's
matrix object
to
match the new transform function
value
If the
SVGTransform
object
reflects an element of a
presentation attribute value
, then
reserialize
the
reflected attribute.
This specification imposes additional requirements on the behavior of
DOMMatrix
objects beyond those described in the
Geometry Interfaces
specification, so that they can be used to reflect presentation attributes
that take transform values.
Every
DOMMatrix
object operates in one of two modes.
It can:
reflect an
SVGTransform
(being exposed through the
matrix
IDL attribute on
an
SVGTransform
), or
be detached
, which is the case for
DOMMatrix
objects
created using their constructor or with
createSVGMatrix
DOMMatrix
can be designated as
read only
which means that attempts to modify the object will result in an exception
being thrown. When assigning to any of a read only
DOMMatrix
's
IDL attributes, or when invoking any of its mutable transform methods,
NoModificationAllowedError
exception will be
thrown
instead of updating the internal value.
Note that this applies only to the read-write
DOMMatrix
interface; the
DOMMatrixReadOnly
interface, which is not used for reflecting
transform
, will already throw an exception if an attempt is made to modify it.
When assigning to any of a writable
DOMMatrix
's
IDL attributes, or when invoking any of its mutable transform methods,
the following steps are run after updating the internal matrix value:
If the
DOMMatrix
reflects an SVGTransform
then:
If the
DOMMatrix
would return true from its
is2d
method, then set the
SVGTransform
object's
value
to a
matrix(…)
value that represents the same matrix as the
DOMMatrix
Otherwise, set the
SVGTransform
object's
value
to a
matrix3d(…)
value that represents the same matrix as the
DOMMatrix
If the
SVGTransform
object
reflects an element of a
presentation attribute value
, then
reserialize
the
reflected attribute.
8.14.2. Interface SVGTransformList
The
SVGTransformList
interface is a
list interface
whose elements are
SVGTransform
objects. An
SVGTransformList
represents a value that the
transform
property can take, namely
either a

or the keyword
none
Exposed
=Window]
interface
SVGTransformList

readonly attribute unsigned long
length
readonly attribute unsigned long
numberOfItems

undefined
clear
();
SVGTransform
initialize
SVGTransform
newItem);
getter
SVGTransform
getItem
(unsigned long index);
SVGTransform
insertItemBefore
SVGTransform
newItem, unsigned long index);
SVGTransform
replaceItem
SVGTransform
newItem, unsigned long index);
SVGTransform
removeItem
(unsigned long index);
SVGTransform
appendItem
SVGTransform
newItem);
setter
undefined (unsigned long index,
SVGTransform
newItem);
// Additional methods not common to other list interfaces.
SVGTransform
createSVGTransformFromMatrix
(optional
DOMMatrix2DInit
matrix = {});
SVGTransform
consolidate
();
};
The
createSVGTransformFromMatrix
method is used to create a new
SVGTransform
object from a matrix object.
When the createSVGTransformFromMatrix(
matrix
) method is called,
the following steps are run:
Let
transform
be a newly created
SVGTransform
object
that is
detached
Follow the steps that would be run if the
setMatrix
method on
transform
were called, passing
matrix
as its argument.
Return
transform
The
consolidate
method is used to convert the transform list into an equivalent
transformation using a single transform function. When the
consolidate() method is called, the following steps are run:
If the
SVGTransformList
object is
read only
then
throw
NoModificationAllowedError
If the list is empty, return null.
Detach
and then remove all elements in the list.
Let
transform
be a newly created
SVGTransform
object.
Let
matrix
be the matrix value obtained by beginning
with an identity matrix, and then post-multiplying the
value of the
matrix object
for each
SVGTransform
in the list, in order.
Set the components of
transform
's
matrix object
to the component values in
matrix
If
transform
's
matrix object
would return true from its
is2d
method, then set
transform
's
value
to a
matrix(…)
value that represents the same matrix as the
matrix object
Otherwise, set
transform
's
value
to a
matrix3d(…)
value that represents the same matrix as the
matrix object
Attach
transform
to this
SVGTransformList
Append
transform
to this list.
If the list
reflects
a presentation attribute, then
reserialize
the reflected attribute.
Return
transform
The behavior of all other interface members of
SVGLengthList
are
defined in
List interfaces
8.14.3. Interface SVGAnimatedTransformList
An
SVGAnimatedTransformList
object is used to
reflect
the
transform
property and its corresponding presentation attribute
(which, depending on the element, is
‘transform’
gradientTransform
or
patternTransform
).
Exposed
=Window]
interface
SVGAnimatedTransformList
SameObject
] readonly attribute
SVGTransformList
baseVal
SameObject
] readonly attribute
SVGTransformList
animVal
};
The
baseVal
and
animVal
IDL attributes
represent the value of the reflected presentation attribute.
On getting
baseVal
or
animVal
, an
SVGTransformList
object is returned that reflects the given
presentation attribute.
8.14.4. Interface SVGPreserveAspectRatio
The
SVGPreserveAspectRatio
interface is used to represent
values for the
preserveAspectRatio
attribute.
An
SVGPreserveAspectRatio
object can be designated as
read only
which means that attempts to modify the object will result in an exception
being thrown, as described below.
Every
SVGPreserveAspectRatio
object
reflects the base value
of a
reflected
preserveAspectRatio
attribute (being exposed through the methods on the
baseVal
or
animVal
member of
an
SVGAnimatedPreserveAspectRatio
).
Exposed
=Window]
interface
SVGPreserveAspectRatio

// Alignment Types
const unsigned short
SVG_PRESERVEASPECTRATIO_UNKNOWN
= 0;
const unsigned short
SVG_PRESERVEASPECTRATIO_NONE
= 1;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMINYMIN
= 2;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMIDYMIN
= 3;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMAXYMIN
= 4;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMINYMID
= 5;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMIDYMID
= 6;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMAXYMID
= 7;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMINYMAX
= 8;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMIDYMAX
= 9;
const unsigned short
SVG_PRESERVEASPECTRATIO_XMAXYMAX
= 10;

// Meet-or-slice Types
const unsigned short
SVG_MEETORSLICE_UNKNOWN
= 0;
const unsigned short
SVG_MEETORSLICE_MEET
= 1;
const unsigned short
SVG_MEETORSLICE_SLICE
= 2;

attribute unsigned short
align
attribute unsigned short
meetOrSlice
};
The numeric alignment type constants defined on
SVGPreserveAspectRatio
are used to represent the alignment keyword values that
preserveAspectRatio
can take. Their meanings are as follows:
Constant
Meaning
SVG_PRESERVEASPECTRATIO_NONE
The
none
keyword.
SVG_PRESERVEASPECTRATIO_XMINYMIN
The
xMinYMin
keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMIN
The
xMidYMin
keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMIN
The
xMaxYMin
keyword.
SVG_PRESERVEASPECTRATIO_XMINYMID
The
xMinYMid
keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMID
The
xMidYMid
keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMID
The
xMaxYMid
keyword.
SVG_PRESERVEASPECTRATIO_XMINYMAX
The
xMinYMax
keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMAX
The
xMidYMax
keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMAX
The
xMaxYMax
keyword.
SVG_PRESERVEASPECTRATIO_UNKNOWN
Some other type of value.
Similarly, the numeric meet-or-slice type constants defined on
SVGPreserveAspectRatio
are used to represent the meet-or-slice
keyword values that
preserveAspectRatio
can take. Their
meanings are as follows:
Constant
Meaning
SVG_MEETORSLICE_MEET
The
meet
keyword.
SVG_MEETORSLICE_SLICE
The
slice
keyword.
SVG_MEETORSLICE_UNKNOWN
Some other type of value.
The
align
IDL attribute
represents the alignment keyword part of the
preserveAspectRatio
value. On getting, the following steps are run:
Let
value
reflect the base value
of a
preserveAspectRatio
attribute.
value
is the current non-animated value of the attribute
(using the attribute's
initial value
if it is not present or invalid).
Return the constant value as specified in the alignment
constant table above for the alignment keyword in
value
On setting
align
, the
following steps are run:
If the
SVGPreserveAspectRatio
is
read only
, then
throw
NoModificationAllowedError
If
value
is
SVG_PRESERVEASPECTRATIO_UNKNOWN
or does not have a corresponding entry in the
alignment keyword table above, then throw a
TypeError
Let
string
be the corresponding keyword
in the alignment keyword table above for
value
Append a single U+0020 SPACE character to
string
Let
meet or slice
be the value that would be
returned from the
meetOrSlice
member on this
SVGPreserveAspectRatio
Append to
string
the corresponding keyword
in the meet-or-slice keyword table above for
meet or slice
Set the reflected
preserveAspectRatio
attribute to
string
The
meetOrSlice
IDL attribute
represents the alignment keyword part of the
preserveAspectRatio
value. On getting, the following steps are run:
Let
value
be a
preserveAspectRatio
value that
reflects the base value
of a
preserveAspectRatio
attribute
value
is the current non-animated value of the attribute.
If the meet-or-slice value is not present in
value
then return
SVG_MEETORSLICE_MEET
Otherwise, the meet-or-slice value is present. Return the constant
value as specified in the meet-or-slice constant table above for the meet-or-slice
keyword in
value
On setting
meetOrSlice
, the
following steps are run:
If the
SVGPreserveAspectRatio
is
read only
, then
throw
NoModificationAllowedError
If
value
is
SVG_MEETORSLICE_UNKNOWN
or does not have a corresponding entry in the
meet-or-slice keyword table above, then throw a
TypeError
Let
align
be the value that would be
returned from the
align
member on this
SVGPreserveAspectRatio
Let
string
be the corresponding keyword
in the alignment keyword table above for
align
Append a single U+0020 SPACE character to
string
Append to
string
the corresponding keyword
in the meet-or-slice keyword table above for
value
Set the reflected
preserveAspectRatio
attribute to
string
8.14.5. Interface SVGAnimatedPreserveAspectRatio
An
SVGAnimatedPreserveAspectRatio
object is used to
reflect
the
preserveAspectRatio
attribute.
Exposed
=Window]
interface
SVGAnimatedPreserveAspectRatio
SameObject
] readonly attribute
SVGPreserveAspectRatio
baseVal
SameObject
] readonly attribute
SVGPreserveAspectRatio
animVal
};
The
baseVal
and
animVal
IDL
attributes represent the current non-animated value of the reflected
preserveAspectRatio
attribute. On getting
baseVal
or
animVal
an
SVGPreserveAspectRatio
object is returned that
reflects the base value
of the
preserveAspectRatio
attribute on the SVG element that the object with the reflecting IDL attribute
of type
SVGAnimatedPreserveAspectRatio
was obtained from.
Chapter 9: Paths
9.1. Introduction
A path represents the outline of a shape which can be filled or
stroked. A path can also be used as a clipping path, to describe
animation, or position text. A path can be used for more than one of
these functions at the same time. (See
Filling, Stroking and Paint Servers
Clipping and Masking
Animation (
'animateMotion'
),
and
Text on a Path
.)
A path is described using the concept of a current point. In
an analogy with drawing on paper, the current point can be
thought of as the location of the pen. The position of the pen
can be changed, and the outline of a shape (open or closed) can
be traced by dragging the pen in either straight lines or
curves.
Paths represent the geometry of the outline of an object,
defined in terms of
moveto
(set a new current point),
lineto
(draw a straight line),
curveto
(draw
a curve using a cubic Bézier),
arc
(elliptical
or circular arc) and
closepath
(close the current
shape by connecting to the last
moveto
) commands.
Compound paths (i.e., a path with multiple subpaths) are
possible to allow effects such as "donut holes" in objects.
This chapter describes the syntax, behavior and DOM
interfaces for SVG paths. Various implementation notes for SVG
paths can be found in
‘path’
element implementation
Notes
A path is defined in SVG using the
path
element.
The
basic shapes
are all described in terms of what their
equivalent path
is, which is
what their shape is as a path. (The equivalent path of a
path
element is simply the path itself.)
In order to define the basic shapes as equivalent paths,
segment-completing close path
operation is defined,
which cannot currently be represented in the basic path syntax.
9.2. The
‘path’
element
path
Categories:
Graphics element
renderable element
shape 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
clipPath
marker
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
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
pathLength
Geometry properties:
DOM Interfaces:
SVGPathElement
The outline of a shape for a
path
element is specified using the
property. See
Path data
below.
9.3. Path data
9.3.1. General information about path data
A path is defined by including a
path
element on which the
property specifies the
path data. The path data contains the
moveto
lineto
curveto
(both cubic and
quadratic Béziers),
arc
and
closepath
instructions.
Example triangle01
specifies a path in the shape of a triangle. (The
indicates a
moveto
, the
s indicate
lineto
s, and the
indicates a
closepath
).



A path that draws a triangle
fill="none" stroke="blue" />
fill="red" stroke="blue" stroke-width="3" />

Example triangle01
View this example as SVG (SVG-enabled browsers only)
Path data can contain newline characters and thus can be
broken up into multiple lines to improve readability.
Newlines inside attributes in markup will be normalized to space
characters while parsing.
The syntax of path data is concise in order to allow for
minimal file size and efficient downloads, since many SVG files
will be dominated by their path data. Some of the ways that SVG
attempts to minimize the size of path data are as follows:
All instructions are expressed as one character (e.g., a
moveto
is expressed as an
).
Superfluous white space and separators (such as commas) may
be eliminated; for instance, the following contains unnecessary
spaces:
M 100 100 L 200 200
It may be expressed more compactly as:
M100 100L200 200
A command letter may be eliminated if an identical command
letter would otherwise precede it; for instance, the following
contains an unnecessary second "L" command:
M 100 200 L 200 100 L -100 -200
It may be expressed more compactly as:
M 100 200 L 200 100 -100 -200
For most commands there are absolute and relative
versions available (uppercase means absolute coordinates,
lowercase means relative coordinates).
Alternate forms of
lineto
are available to
optimize the special cases of horizontal and vertical lines
(absolute and relative).
Alternate forms of
curve
are available to
optimize the special cases where some of the control points
on the current segment can be determined automatically from
the control points on the previous segment.
The path data syntax is a prefix notation (i.e., commands
followed by parameters). The only allowable decimal point is a
Unicode
U+002E FULL STOP (".") character (also referred to in Unicode as
PERIOD, dot and decimal point) and no other delimiter
characters are allowed [
UNICODE
].
(For example, the following is an
invalid numeric value in a path data stream: "13,000.56".
Instead, say: "13000.56".)
For the relative versions of the commands, all coordinate
values are relative to the current point at the start of the
command.
In the tables below, the following notation is used to
describe the syntax of a given path command:
(): grouping of parameters
+: 1 or more of the given parameter(s) is required
In the description of the path commands,
cpx
and
cpy
represent the coordinates of the current point.
9.3.2. Specifying path data: the ‘
’ property
Name:
Value:
none |

Initial:
none
Applies to:
path
Inherited:
no
Percentages:
N/A
Media:
visual
Computed value:
as specified
Animation type
See prose
The
property is used to specify the shape of a
path
element.
The value
none
indicates that there is no
path data for the element. For
path
elements, this means that the
element does not render or contribute to the
bounding box
of ancestor
container elements
A path is made up of multiple segments, and every command, either explicit
or implicit, other than moveto or closepath,
defines one
path segment
All coordinates and lengths specified within path data must be treated as
being in
user units
in the current user coordinate system.
The

value
specifies a shape using a path data string. The contents of the

value must match the
svg-path
EBNF grammar
defined below, and errors within the string are handled according to
the rules in the
Path Data Error Handling
section.
If the path data string contains no valid commands, then the behavior
is the same as the
none
value.
For animation, two
property values can only be
interpolated smoothly when the path data strings contain have the
same structure, (i.e. exactly the same number and types of path data
commands which are in the same order). If an animation is specified
and the lists of path data commands do not have the same structure,
then the values must be
interpolated
using the
discrete
animation type.
If the list of path data commands have the same structure, then each
parameter to each path data command must be
interpolated
separately
as
real numbers
. Flags and booleans must be interpolated as
fractions between zero and one, with any non-zero value considered
to be a value of one/true.
Resolved that "d will become a presentation attribute (no name
change) with path data string as value" at
London
Editor's Meeting
The following sections list the commands that can be used
in path data strings. Those that
draw straight line segments include the
lineto commands
and
and the
close path commands
and
). These three groups of commands draw curves:
Cubic
Bézier commands
and
). A cubic Bézier segment is defined
by a start point, an end point, and two control points.
Quadratic
Bézier commands
and
). A quadratic Bézier segment is
defined by a start point, an end point, and one control
point.
Elliptical
arc commands
and
).
An elliptical arc segment draws a segment of an ellipse.
9.3.3. The
"moveto"
commands
The "moveto" commands (
or
) must establish a new
initial point
and a new current point. The effect is as if the "pen" were lifted and moved to
a new location. A path data segment (if there is one) must begin with a "moveto"
command. Subsequent "moveto" commands (i.e., when the "moveto"
is not the first command) represent the start of a new
subpath
Command
Name
Parameters
Description
(absolute)
(relative)
moveto
(x y)+
Start a new sub-path at the given (x,y) coordinates.
(uppercase) indicates that absolute
coordinates will follow;
(lowercase)
indicates that relative coordinates will follow. If a moveto is
followed by multiple pairs of coordinates, the subsequent pairs
are treated as implicit lineto commands. Hence, implicit lineto
commands will be relative if the moveto is relative, and
absolute if the moveto is absolute. If a relative moveto
) appears as the first element of the path,
then it is treated as a pair of absolute coordinates. In this
case, subsequent pairs of coordinates are treated as relative
even though the initial moveto is interpreted as an absolute moveto.
When a relative
command is used, the
position moved to is (
cpx
cpy
).
9.3.4. The
"closepath"
command
The "closepath" (
or
ends the current subpath by connecting it back to its
initial point
An automatic
straight line is drawn from the current point to the
initial point
of the current subpath. This
path segment
may be of zero
length.
If a "closepath" is followed immediately by a "moveto", then the
"moveto" identifies the start point of the next subpath.
If a "closepath" is followed immediately by any other command, then
the next subpath starts at the same initial point as the current
subpath.
When a subpath ends in a "closepath," it differs in behavior
from what happens when "manually" closing a subpath via a
"lineto" command in how
‘stroke-linejoin’
and
‘stroke-linecap’
are implemented. With "closepath", the end of the final segment
of the subpath is "joined" with the start of the initial
segment of the subpath using the current value of
‘stroke-linejoin’
If you instead "manually" close the subpath via a "lineto"
command, the start of the first segment and the end of the last
segment are not joined but instead are each capped using the
current value of
‘stroke-linecap’
At the end of the command, the new current point is set to the
initial point of the current subpath.
Command
Name
Parameters
Description
or
closepath
(none)
Close the current subpath by connecting it back to the current
subpath's
initial point
(see prose above). Since the
and
commands take no parameters, they have an identical effect.
closed subpath
must be closed with a
"closepath" command, this "joins" the first and last
path segments
Any other path is an
open subpath
closed subpath
differs in behavior
from an
open subpath
whose final coordinate is the
initial point
of the subpath.
The first and last
path segments
of an
open subpath
will not be
joined, even when the final coordinate of the last
path segment
is the
initial point
of the subpath. This will result in the first and last
path segments
being capped using the current value of
stroke-linecap
rather than joined using the current value of
stroke-linejoin
If a "closepath" is followed immediately by a
"moveto", then the "moveto" identifies the start point of the
next subpath. If a "closepath" is followed immediately by any
other command, then the next subpath must start at the same
initial point
as the current subpath.
9.3.4.1. Segment-completing close path operation
In order to represent the basic shapes as equivalent paths,
there must be a way to close curved shapes
without introducing an additional straight-line segment
(even if that segment would have zero length).
For that purpose, a segment-completing close path operation is defined here.
segment-completing close path
operation
combines
with the previous path command,
with two effects:
It ensures that the final coordinate point of the previous command exactly matches
the
initial point
of the current subpath.
It joins the final and initial points of the subpath, making it a closed subpath.
Segment-completing close path operations are not currently supported
as a command in the path data syntax.
The working group has proposed such a syntax for future versions of the specification.
9.3.5. The
"lineto"
commands
The various "lineto" commands draw straight lines from the
current point to a new point:
Command
Name
Parameters
Description
(absolute)
(relative)
lineto
(x y)+
Draw a line from the current point to the given (x,y)
coordinate which becomes the new current point.
(uppercase) indicates that absolute
coordinates will follow;
(lowercase)
indicates that relative coordinates will follow. A number
of coordinates pairs may be specified to draw a polyline.
At the end of the command, the new current point is set to
the final set of coordinates provided.
(absolute)
(relative)
horizontal lineto
x+
Draws a horizontal line from the current point.
(uppercase) indicates
that absolute coordinates will follow;
(lowercase) indicates that relative coordinates will
follow. Multiple x values can be provided (although usually
this doesn't make sense). An
or
command is equivalent to an
or
command with 0 specified for the y coordinate.
At the end of the command, the new current point is
taken from the final coordinate value.
(absolute)
(relative)
vertical lineto
y+
Draws a vertical line from the current point.
(uppercase) indicates that
absolute coordinates will follow;
(lowercase) indicates that relative coordinates will
follow. Multiple y values can be provided (although usually
this doesn't make sense). A
or
command is equivalent to an
or
command with 0 specified for the x coordinate.
At the end of the command, the new current point is
taken from the final coordinate value.
When a relative
command is used, the
end point of the line is (
cpx
cpy
).
When a relative
command is used,
the end point of the line is (
cpx
cpy
). This means
that an
command with a positive
value draws a horizontal line in the direction of the positive x-axis.
When a relative
command is used,
the end point of the line is (
cpx
cpy
).
9.3.6. The cubic Bézier curve commands
The cubic Bézier commands are as follows:
Command
Name
Parameters
Description
(absolute)
(relative)
curveto
(x1 y1 x2 y2 x y)+
Draws a cubic Bézier curve from the current
point to (x,y) using (x1,y1) as the control point at the
beginning of the curve and (x2,y2) as the control point at
the end of the curve.
(uppercase)
indicates that absolute coordinates will follow;
(lowercase) indicates that relative
coordinates will follow. Multiple sets of coordinates may
be specified to draw a polybézier. At the end of the
command, the new current point becomes the final (x,y)
coordinate pair used in the polybézier.
(absolute)
(relative)
shorthand/smooth curveto
(x2 y2 x y)+
Draws a cubic Bézier curve from the current
point to (x,y). The first control point is assumed to be
the reflection of the second control point on the previous
command relative to the current point. (If there is no
previous command or if the previous command was not an C,
c, S or s, assume the first control point is coincident
with the current point.) (x2,y2) is the second control
point (i.e., the control point at the end of the curve).
(uppercase) indicates that absolute
coordinates will follow;
(lowercase)
indicates that relative coordinates will follow. Multiple
sets of coordinates may be specified to draw a
polybézier. At the end of the command, the new
current point becomes the final (x,y) coordinate pair used
in the polybézier.
When a relative
or
command is used, each of the relative coordinate pairs
is computed as for those in an
command.
For example, the final control point of the curve of
both commands is (
cpx
cpy
).
Example cubic01
shows some
simple uses of cubic Bézier commands within a path. The
example uses an internal CSS style sheet to assign styling
properties. Note that the control point for the "S" command is
computed automatically as the reflection of the control point
for the previous "C" command relative to the start point of the
"S" command.



Picture showing a simple example of path data
using both a "C" and an "S" command,
along with annotations showing the control points
and end points

M100,200 C100,100 250,100 250,200
style="text-anchor:middle">S400,300 400,200

Example cubic01
View this example as SVG (SVG-enabled browsers only)
The following picture shows some how cubic Bézier
curves change their shape depending on the position of the
control points. The first five examples illustrate a single
cubic Bézier
path segment
. The example at the lower
right shows a "C" command followed by an "S" command.
View
this example as SVG (SVG-enabled browsers only)
9.3.7. The quadratic Bézier curve commands
The quadratic Bézier commands are as follows:
Command
Name
Parameters
Description
(absolute)
(relative)
quadratic Bézier curveto
(x1 y1 x y)+
Draws a quadratic Bézier curve from the current
point to (x,y) using (x1,y1) as the control point.
(uppercase) indicates that absolute
coordinates will follow;
(lowercase)
indicates that relative coordinates will follow. Multiple
sets of coordinates may be specified to draw a
polybézier. At the end of the command, the new
current point becomes the final (x,y) coordinate pair used
in the polybézier.
(absolute)
(relative)
Shorthand/smooth quadratic Bézier curveto
(x y)+
Draws a quadratic Bézier curve from the current
point to (x,y). The control point is assumed to be the
reflection of the control point on the previous command
relative to the current point. (If there is no previous
command or if the previous command was not a Q, q, T or t,
assume the control point is coincident with the current
point.)
(uppercase) indicates that
absolute coordinates will follow;
(lowercase) indicates that relative coordinates will
follow. At the end of the command, the new current point
becomes the final (x,y) coordinate pair used in the
polybézier.
When a relative
or
command is used, each of the relative coordinate pairs
is computed as for those in an
command.
For example, the final control point of the curve of
both commands is (
cpx
cpy
).
Example quad01
shows some
simple uses of quadratic Bézier commands within a path.
Note that the control point for the "T" command is computed
automatically as the reflection of the control point for the
previous "Q" command relative to the start point of the "T"
command.



Picture showing a "Q" a "T" command,
along with annotations showing the control points
and end points
fill="none" stroke="blue" stroke-width="1" />

fill="none" stroke="red" stroke-width="5" />











fill="none" stroke="#888888" stroke-width="2" />

Example quad01
View this example as SVG (SVG-enabled browsers only)
9.3.8. The elliptical arc curve commands
SVG 2 Requirement:
Make it simpler to draw arcs in SVG path syntax.
Resolution:
Make arcs in paths easier.
Purpose:
To make it easier for authors to write path data with arcs by hand.
Owner:
Cameron (
ACTION-3151
The elliptical arc commands are as follows:
Command
Name
Parameters
Description
(absolute)
(relative)
elliptical arc
(rx ry x-axis-rotation large-arc-flag sweep-flag x
y)+
Draws an elliptical arc from the current point to
). The size and
orientation of the ellipse are defined by two radii
rx
ry
) and an
x-axis-rotation
, which indicates how the
ellipse as a whole is rotated, in degrees, relative to the current
coordinate system. The center (
cx
cy
) of the ellipse is calculated
automatically to satisfy the constraints imposed by the
other parameters.
large-arc-flag
and
sweep-flag
contribute to the automatic
calculations and help determine how the arc is drawn.
When a relative
command is used, the end point
of the arc is (
cpx
cpy
).
Example arcs01
shows some
simple uses of arc commands within a path.



Picture of a pie chart with two pie wedges and
a picture of a line with arc blips
fill="none" stroke="blue" stroke-width="1" />

fill="red" stroke="blue" stroke-width="5" />
fill="yellow" stroke="blue" stroke-width="5" />

fill="none" stroke="red" stroke-width="5" />

Example arcs01
View this example as SVG (SVG-enabled browsers only)
The elliptical arc command draws a section of an ellipse
which must meet the following constraints:
the arc starts at the current point
the arc ends at point (
the ellipse has the two radii (
rx
ry
the x-axis of the ellipse is rotated by
x-axis-rotation
degrees relative to the x-axis of
the current coordinate system.
For most situations, there are actually four different arcs
(two different ellipses, each with two different arc sweeps)
that satisfy these constraints.
large-arc-flag
and
sweep-flag
indicate which one of the four
arcs are drawn, as follows:
Of the four candidate arc sweeps, two will represent an
arc sweep of greater than or equal to 180 degrees (the
"large-arc"), and two will represent an arc sweep of less
than or equal to 180 degrees (the "small-arc"). If
large-arc-flag
is '1', then one of the two
larger arc sweeps will be chosen; otherwise, if
large-arc-flag
is '0', one of the smaller
arc sweeps will be chosen,
If
sweep-flag
is '1', then the arc will
be drawn in a "positive-angle" direction (i.e., the ellipse
formula x=
cx
rx
*cos(theta)
and y=
cy
ry
*sin(theta) is
evaluated such that theta starts at an angle corresponding to
the current point and increases positively until the arc
reaches (x,y)). A value of 0 causes the arc to be drawn in a
"negative-angle" direction (i.e., theta starts at an angle
value corresponding to the current point and decreases until
the arc reaches (x,y)).
The following illustrates the four combinations of
large-arc-flag
and
sweep-flag
and the four different arcs that will be drawn based on the
values of these flags. For each case, the following path data
command was used:
style="fill:none; stroke:red; stroke-width:6"/>
where "?,?" is replaced by "0,0" "0,1" "1,0" and "1,1" to
generate the four possible cases.
View
this example as SVG (SVG-enabled browsers only)
Refer to the section on
Out-of-range elliptical arc parameters
for detailed implementation notes for
the path data elliptical arc commands.
The
Implementation Notes appendix
has relevant formulae for software that needs to convert
SVG arc notation to a format that uses center points and arc sweeps.
9.3.9. The grammar for path data
SVG path data matches the following EBNF grammar.
svg_path::= wsp* (moveto (wsp* drawto_command)*)? wsp*

drawto_command::=
moveto
| closepath
| lineto
| horizontal_lineto
| vertical_lineto
| curveto
| smooth_curveto
| quadratic_bezier_curveto
| smooth_quadratic_bezier_curveto
| elliptical_arc

moveto::=
( "M" | "m" ) wsp* coordinate_pair_sequence

closepath::=
("Z" | "z")

lineto::=
("L"|"l") wsp* coordinate_pair_sequence

horizontal_lineto::=
("H"|"h") wsp* coordinate_sequence

vertical_lineto::=
("V"|"v") wsp* coordinate_sequence

curveto::=
("C"|"c") wsp* curveto_coordinate_sequence

curveto_coordinate_sequence::=
coordinate_pair_triplet
| (coordinate_pair_triplet comma_wsp? curveto_coordinate_sequence)

smooth_curveto::=
("S"|"s") wsp* smooth_curveto_coordinate_sequence

smooth_curveto_coordinate_sequence::=
coordinate_pair_double
| (coordinate_pair_double comma_wsp? smooth_curveto_coordinate_sequence)

quadratic_bezier_curveto::=
("Q"|"q") wsp* quadratic_bezier_curveto_coordinate_sequence

quadratic_bezier_curveto_coordinate_sequence::=
coordinate_pair_double
| (coordinate_pair_double comma_wsp? quadratic_bezier_curveto_coordinate_sequence)

smooth_quadratic_bezier_curveto::=
("T"|"t") wsp* coordinate_pair_sequence

elliptical_arc::=
( "A" | "a" ) wsp* elliptical_arc_argument_sequence

elliptical_arc_argument_sequence::=
elliptical_arc_argument
| (elliptical_arc_argument comma_wsp? elliptical_arc_argument_sequence)

elliptical_arc_argument::=
number comma_wsp? number comma_wsp? number comma_wsp
flag comma_wsp? flag comma_wsp? coordinate_pair

coordinate_pair_double::=
coordinate_pair comma_wsp? coordinate_pair

coordinate_pair_triplet::=
coordinate_pair comma_wsp? coordinate_pair comma_wsp? coordinate_pair

coordinate_pair_sequence::=
coordinate_pair | (coordinate_pair comma_wsp? coordinate_pair_sequence)

coordinate_sequence::=
coordinate | (coordinate comma_wsp? coordinate_sequence)

coordinate_pair::= coordinate comma_wsp? coordinate

coordinate::= sign? number

sign::= "+"|"-"

exponent::= ("e" | "E") sign? digit+

fractional-constant::= (digit* "." digit+) | digit+

number::= fractional-constant exponent?

flag::= ("0" | "1")

comma_wsp::= (wsp+ ","? wsp*) | ("," wsp*)

wsp::= (#x9 | #x20 | #xA | #xC | #xD)

digit::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
The processing of the EBNF must consume as much of a given
EBNF production as possible, stopping at the point when a
character is encountered which no longer satisfies the
production. Thus, in the string "M 100-200", the first
coordinate for the "moveto" consumes the characters "100" and
stops upon encountering the minus sign because the minus sign
cannot follow a digit in the production of a "coordinate". The
result is that the first coordinate will be "100" and the
second coordinate will be "-200".
Similarly, for the string "M 0.6.5", the first coordinate of
the "moveto" consumes the characters "0.6" and stops upon
encountering the second decimal point because the production of
a "coordinate" only allows one decimal point. The result is
that the first coordinate will be "0.6" and the second
coordinate will be ".5".
The
grammar
of previous specifications
allowed a trailing decimal point without
any decimal digits for numbers (e.g.
23.
). SVG 2 harmonizes number parsing
with CSS [
css-syntax-3
],
disallowing the relaxed grammar for numbers. However, user agents may continue
to accept numbers with trailing decimal points when parsing is unambiguous.
Authors and authoring tools must not use the disallowed number format.
The EBNF allows the path data string in the
property to be empty. An empty path data string
disables rendering of the path.
Rendering is also disabled when the
property
has the value
none
If path data not matching the grammar is encountered, then the path data is in error
(see
Error Handling
).
9.4. Path directionality
Some features, such as the
orientation
of
markers
and the
shapes
of
line caps
, are defined in terms of
the direction of the path at a given distance along the path or at the
start or end of an individual segment.
The
direction of a path
at a specified
distance along the path is defined as follows:
If the given distance is zero, then the direction of the path is
the
direction at the start of
the path's first segment
Otherwise, if the given distance is the length of the path, then
the direction of the path is the
direction at the end of the path's
last segment
Otherwise, if the given distance along the path occurs at a path
segment boundary, then the direction of the path is the
direction at the start of
the segment at the given distance
, considering each segment to
be endpoint exclusive.
This will "move past"
zero length segments, and choose the later segment if the distance
is at the boundary between two non-zero length segments.
The default direction at segment boundaries is overriden
when calculating a
cap shape
and when
rendering markers
Otherwise, the given distance along the path occurs in the middle
of a non-zero length
path segment
. The direction is simply the direction
of the curve at that point. If the point lies at a discontinuity, such as
a cusp in a Bézier segment, then the direction is undefined; in this case,
a direction between the incoming and outgoing direction around the discontinuity
should be used.
The
direction at the start
of a
path segment
is defined as follows:
If length of the entire path the segment belongs to is zero, then the
direction at the start of the segment points in the same direction as the
positive x-axis.
Otherwise, if the
path segment
is zero length and the segment does not
have any preceding non-zero length segments, then the direction at the
start of the segment is the same as the
direction at the end of the segment
Otherwise, if the
path segment
is zero length and there is some non-zero
length segment preceding this segment, then the direction at the start of
this segment is the same as the
direction at the end of the closest
preceding non-zero length segment
Otherwise, the
path segment
is non-zero length. The direction at the
start of the segment is simply the direction coming out of the segment's start
point.
The
direction at the end of a path
segment
is defined as follows:
If length of the entire path the segment belongs to is zero, then the
direction at the end of the segment points in the same direction as the
positive x-axis.
Otherwise, if the
path segment
is zero length and the segment does not
have any following non-zero length segments, then the direction at the
end of the segment is the same as the
direction at the start of the segment
Otherwise, if the
path segment
is zero length and there is some non-zero
length segment following this segment, then the direction at the end of
this segment is the same as the
direction at the start of the closest
following non-zero length segment
Otherwise, the
path segment
is non-zero length. The direction at the
end of the segment is simply the direction coming in to the segment's end
point.
9.5. Implementation notes
A conforming SVG user agent must implement features that use path data
according to the following details:
9.5.1. Out-of-range elliptical arc parameters
Arbitrary numerical values are permitted for all elliptical arc parameters
(other than the boolean flags),
but user agents must make the following adjustments for invalid values
when rendering curves or calculating their geometry:
If the endpoint (
) of the segment
is identical to the current point
(e.g., the endpoint of the previous segment),
then this is equivalent to omitting the elliptical arc segment entirely.
If either
rx
or
ry
is 0,
then this arc is treated as a straight line segment
(a "lineto") joining the endpoints.
If either
rx
or
ry
have negative signs, these are dropped;
the absolute value is used instead.
If
rx
ry
and
x-axis-rotation
are such that there is no solution
(basically, the ellipse is not big enough to reach
from the current point to the new endpoint)
then the ellipse is scaled up
uniformly until there is exactly one solution (until the
ellipse is just big enough).
See the appendix section
Correction of out-of-range radii
for mathematical formula for this scaling operation.
This forgiving yet consistent treatment of out-of-range
values ensures that:
The inevitable approximations arising from computer
arithmetic cannot cause a valid set of values written by one
SVG implementation to be treated as invalid when read by
another SVG implementation. This would otherwise be a
problem for common boundary cases such as a semicircular
arc.
Continuous animations that cause parameters to pass
through invalid values are not a problem. The motion
remains continuous.
9.5.2. Reflected control points
The S/s and T/t commands indicate that the first control point of
the given cubic Bézier segment is calculated by
reflecting the previous path segment's final control point
relative to the current point. The exact math is as
follows.
If the current point is (
curx
cury
) and the
final control point of the previous
path segment
is
oldx2
oldy2
), then the reflected point (i.e., (
newx1
newy1
), the first control point of the current
path segment
) is:
(newx1, newy1) = (curx - (oldx2 - curx), cury - (oldy2 - cury))
= (2*curx - oldx2, 2*cury - oldy2)
9.5.3. Zero-length path segments
Path segments with zero length are not invalid,
and will affect rendering in the following cases:
If markers are specified, then a marker is drawn on
every applicable vertex, even if the given vertex is the
end point of a zero-length
path segment
and even if
"moveto" commands follow each other.
As mentioned in
Stroke Properties
linecaps must be painted for zero-length subpaths when
stroke-linecap
has a value of
round
or
square
9.5.4. Error handling in path data
Unrecognized contents within a path data stream (i.e.,
contents that are not part of the path data grammar) is an
error.
In such a case, the following error-handling rules must be used:
The general rule for error handling in path data is
that the SVG user agent shall render a
path
element up
to (but not including) the path command containing the
first error in the path data specification. This will
provide a visual clue to the user or developer about
where the error might be in the path data specification.
This rule will greatly discourage generation of invalid
SVG path data.
If a path data command contains an incorrect set of
parameters, then the given path data command is rendered
up to and including the last correctly defined
path segment
even if that
path segment
is a sub-component of
a compound path data command, such as a "lineto" with
several pairs of coordinates. For example, for the path
data string
'M 10,10 L 20,20,30'
there is an odd number of parameters for the "L" command, which requires an even
number of parameters. The user agent is required to draw
the line from (10,10) to (20,20) and then perform error
reporting since
'L 20 20'
is the last correctly defined segment of the path data specification.
Wherever possible, all SVG user agents shall report
all errors to the user.
9.6. Distance along a path
Various operations, including
text on a path
and
motion animation
and various
stroke
operations
, require that the user agent compute the
distance along the geometry of a graphics element, such as a
path
Exact mathematics exist for computing distance along a path,
but the formulas are highly complex and require substantial
computation. It is recommended that authoring products and user
agents employ algorithms that produce as precise results as
possible; however, to accommodate implementation differences
and to help distance calculations produce results that
approximate author intent, the
pathLength
attribute can be used
to provide the author's computation of the total length of the
path so that the user agent can scale distance-along-a-path
computations by the ratio of
pathLength
to the user agent's own
computed value for total path length.
A "moveto" operation within a
path
element is defined to have
zero length. Only the various "lineto", "curveto" and "arcto"
commands contribute to path length calculations.
9.6.1. The
‘pathLength’
attribute
Name
Value
Initial value
Animatable
pathLength

(none)
yes
The author's computation of the total length of the
path, in user units. This value is used to calibrate the
user agent's own
distance-along-a-path
calculations with that of the author. The user agent will
scale all distance-along-a-path computations by the ratio
of
pathLength
to the user
agent's own computed value for total path length.
pathLength
potentially affects
calculations for
text on a path
motion animation
and
various
stroke operations
A value of zero is valid and must be treated as a scaling factor of infinity.
A value of zero scaled infinitely must remain zero, while any non-percentage value greater
than zero must become +Infinity.
A negative value is an error (see
Error handling
).
pathLength
has no effect on percentage
distance-along-a-path
calculations.
9.7. DOM interfaces
9.7.1. Interface SVGPathElement
An
SVGPathElement
object represents a
path
in the DOM.
Exposed
=Window]
interface
SVGPathElement
SVGGeometryElement
};
Chapter 10: Basic Shapes
10.1. Introduction and definitions
basic shape
shape
shape elements
A graphics element that is defined by some combination of
straight lines and curves. Specifically:
circle
ellipse
line
path
polygon
polyline
and
rect
SVG contains the following set of basic shape elements:
rectangles (including optional rounded corners), created with the
rect
element,
circles, created with the
circle
element,
ellipses, created with the
ellipse
element,
straight lines, created with the
line
element,
polylines, created with the
polyline
element, and
polygons, created with the
polygon
element
Mathematically, these shape elements are equivalent to a
path
element that would construct the same shape. The basic
shapes may be stroked, filled and used as clip paths. All of the
properties available for
path
elements also apply to the basic
shapes.
The
equivalent path
and algorithm to compute the stroke for each shape
are defined in the shape sections below.
10.2. The
‘rect’
element
The
rect
element defines a rectangle which is axis-aligned
with the current
user coordinate system
. Rounded rectangles can be achieved by setting
non-zero values for the
rx
and
ry
geometric properties.
rect
Categories:
Graphics element
renderable element
shape 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
clipPath
marker
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
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
pathLength
Geometry properties:
width
height
rx
ry
DOM Interfaces:
SVGRectElement
The
and
coordinates refer to the left and top edges of the rectangle,
in the current user coordinate system.
The
width
and
height
properties define the overall width and height of the rectangle.
A negative value for either property is
invalid
and must be
ignored
A computed value of zero for either dimension disables rendering of the element.
For rounded rectangles,
the computed values of the
rx
and
ry
properties define
the x- and y-axis radii of elliptical arcs used to round off the corners of the rectangle.
The arc are always symmetrical along both horizontal and vertical axis; to create a rectangle with uneven corner rounding, define the shape explicitly with a
path
A negative value for either property is
invalid
and must be
ignored
A computed value of zero for either dimension,
or a computed value of
auto
for
both
dimensions,
results in a rectangle without corner rounding.
The used values for the x- and y-axis rounded corner radii
may be determined implicitly from the other dimension (using the
auto
value),
and are also subject to clamping so that the lengths of
the straight segments of the rectangle are never negative.
The used values for
rx
and
ry
are determined
from the computed values by following these steps in order:
If both
rx
and
ry
have a computed value of
auto
(since
auto
is the initial value for both properties, this will also occur if neither are specified by the author or if all author-supplied values are invalid),
then the used value of both
rx
and
ry
is 0. (This will result in square corners.)
Otherwise, convert specified values to absolute values as follows:
If
rx
is set to a length value or a percentage,
but
ry
is
auto
calculate an absolute length equivalent for
rx
, resolving percentages against the used
width
of the rectangle;
the absolute value for
ry
is the same.
If
ry
is set to a length value or a percentage,
but
rx
is
auto
calculate the absolute length equivalent for
ry
, resolving percentages against the used
height
of the rectangle;
the absolute value for
rx
is the same.
If both
rx
and
ry
were set to lengths or percentages,
absolute values are generated individually,
resolving
rx
percentages against the used
width
and resolving
ry
percentages against the used
height
Finally, apply clamping to generate the used values:
If the absolute
rx
(after the above steps)
is greater than half of the used
width
then the used value of
rx
is half of the used
width
If the absolute
ry
(after the above steps)
is greater than half of the used
height
then the used value of
ry
is half of the used
height
Otherwise, the used values of
rx
and
ry
are the absolute values computed previously.
Mathematically, a
rect
element is mapped to an
equivalent
path
element as follows,
after generating absolute used values
width
height
rx
, and
rx
in user units for the user coordinate system,
for each of the equivalent geometric properties
following the rules specified above and in
Units
perform an absolute
moveto
operation to
location (
x+rx
);
perform an absolute horizontal
lineto
with parameter
x+width-rx
if
both
rx
and
ry
are greater than zero,
perform an absolute
elliptical arc
operation to coordinate (
x+width
y+ry
),
where
rx
and
ry
are used as the equivalent parameters to
the
elliptical arc
command,
the
x-axis-rotation
and
large-arc-flag
are set to zero,
the
sweep-flag
is set to one;
perform an absolute vertical
lineto
parameter
y+height-ry
if
both
rx
and
ry
are greater than zero,
perform an absolute
elliptical arc
operation to coordinate (
x+width-rx
y+height
),
using the same parameters as previously;
perform an absolute horizontal
lineto
parameter
x+rx
if
both
rx
and
ry
are greater than zero,
perform an absolute
elliptical arc
operation to coordinate (
y+height-ry
),
using the same parameters as previously;
perform an absolute vertical
lineto
parameter
y+ry
if
both
rx
and
ry
are greater than zero,
perform an absolute
elliptical arc
operation with a
segment-completing close path
operation,
using the same parameters as previously.
Path decomposition resolved during teleconference on
June
3rd, 2013
Example rect01
shows a
rectangle with sharp corners. The
rect
element is filled with yellow
and stroked with navy.


Example rect01 - rectangle with sharp corners

fill="none" stroke="blue" stroke-width="2"/>

fill="yellow" stroke="navy" stroke-width="10" />

Example rect01
View this example as SVG (SVG-enabled browsers only)
Example rect02
shows
two rounded rectangles. The
rx
specifies how to round the corners of
the rectangles. Note that since no value has been specified for the
ry
attribute, the used value will be derived from the
rx
attribute.


Example rect02 - rounded rectangles

fill="none" stroke="blue" stroke-width="2"/>

fill="green" />

fill="none" stroke="purple" stroke-width="30" />


Example rect02
View this example as SVG (SVG-enabled browsers only)
10.3. The
‘circle’
element
The
circle
element defines a circle based on a center point and a
radius.
circle
Categories:
Graphics element
renderable element
shape 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
clipPath
marker
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
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
pathLength
Geometry properties:
cx
cy
DOM Interfaces:
SVGCircleElement
The
cx
and
cy
attributes define the coordinates of the center of the circle.
The
attribute defines the radius of the circle.
A negative value is
invalid
and must be
ignored
A computed value of zero disables rendering of the element.
Mathematically, a
circle
element is mapped to an
equivalent
path
element that consists of four
elliptical
arc
segments, each covering a quarter of the circle. The path
begins at the "3 o'clock" point on the radius and proceeds in a
clock-wise direction (before any transformations).
The
rx
and
ry
parameters to the arc commands
are both equal to the used value of the
property, after conversion to local user units,
while the
x-axis-rotation
and the
large-arc-flag
are set to zero,
and the
sweep-flag
is set to one.
The coordinates are computed as follows,
where
cx
cy
, and
are the used values of the equivalent properties, converted to user units:
A move-to command to the point
cx+r
cy
arc to
cx
cy+r
arc to
cx-r
cy
arc to
cx
cy-r
arc with a
segment-completing close path
operation.
Path decomposition resolved during teleconference on
June
3rd, 2013
Example
circle01
consists of a
circle
element that is filled
with red and stroked with blue.


Example circle01 - circle filled with red and stroked with blue

fill="none" stroke="blue" stroke-width="2"/>

fill="red" stroke="blue" stroke-width="10" />

Example circle01
View this example as SVG (SVG-enabled browsers only)
10.4. The
‘ellipse’
element
The
ellipse
element defines an ellipse which is axis-aligned
with the current
user coordinate system
based on a center point and two radii.
ellipse
Categories:
Graphics element
renderable element
shape 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
clipPath
marker
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
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
pathLength
Geometry properties:
cx
cy
rx
ry
DOM Interfaces:
SVGEllipseElement
The
cx
and
cy
coordinates define the center of the ellipse.
The
rx
and
ry
properties define the x- and y-axis radii of the
ellipse.
A negative value for either property is
invalid
and must be
ignored
A computed value of zero for either dimension,
or a computed value of
auto
for
both
dimensions,
disables rendering of the element.
An
auto
value for
either
rx
or
ry
is converted to a used value, following the rules given above for rectangles
(but without any clamping based on
width
or
height
).
Effectively, an
auto
value creates a circular shape
whose radius is defined by a value expressed solely in one dimension;
this allows for creating a circle with a radius defined in terms of one of the following:
a percentage of the coordinate system
width
; that is, a percentage value for
rx
and an
auto
value for
ry
a percentage of the coordinate system
height
; that is, an
auto
value for
rx
and a percentage value for
ry
New in SVG 2.
The
auto
value for
rx
and
ry
was added to allow consistent
parsing of these properties for both ellipses and rectangles.
Previously, if either
rx
or
ry
was unspecified,
the ellipse would not render.
Mathematically, an
ellipse
element is mapped to an
equivalent
path
element that consists of four
elliptical
arc
segments, each covering a quarter of the ellipse. The path
begins at the "3 o'clock" point on the radius and proceeds in a
clock-wise direction (before any transformation).
The
rx
and
ry
parameters to the arc commands
are the used values of the equivalent properties after conversion to local user units,
while the
x-axis-rotation
and the
large-arc-flag
are set to zero,
and the
sweep-flag
is set to one.
The coordinates are computed as follows,
where
cx
cy
rx
, and
ry
are the used values of the equivalent properties, converted to user units:
A move-to command to the point
cx+rx
cy
arc to
cx
cy+ry
arc to
cx-rx
cy
arc to
cx
cy-ry
arc with a
segment-completing close path
operation.
Path decomposition resolved during teleconference on
June
3rd, 2013
Example ellipse01
below specifies
the coordinates of the two ellipses in the user coordinate system
established by the
viewBox
attribute on the
svg
element and the
transform
property on the
and
ellipse
elements. Both ellipses use the default values of
zero for the
cx
and
cy
attributes (the center of the
ellipse). The second ellipse is rotated.


Example ellipse01 - examples of ellipses

fill="none" stroke="blue" stroke-width="2" />

fill="red" />

rx="250" ry="100"
fill="none" stroke="blue" stroke-width="20" />

Example ellipse01
View this example as SVG (SVG-enabled browsers only)
10.5. The
‘line’
element
The
line
element defines a line segment that starts at one point
and ends at another.
line
Categories:
Graphics element
renderable element
shape 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
clipPath
marker
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
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
pathLength
x1
y1
x2
y2
DOM Interfaces:
SVGLineElement
Attribute definitions:
Name
Value
Initial value
Animatable
x1
y1


yes
The x- and y-axis coordinates of the start of the line.
Name
Value
Initial value
Animatable
x2
y2


yes
The x- and y-axis coordinates of the end of the line.
A future specification may convert the
x1
y1
x2
, and
y2
attributes to geometric properties.
Currently, they can only be specified via element attributes, and not CSS.
Mathematically, a
line
element can be mapped to an
equivalent
path
element as follows,
after converting coordinates into user coordinate system user units according
to
Units
to generate values
x1
y1
x2
, and
y2
perform an absolute
moveto
operation to absolute location (
x1
y1
perform an absolute
lineto
operation to absolute location (
x2
y2
Because
line
elements are single lines and thus are geometrically
one-dimensional, they have no interior; thus,
line
elements are never
filled (see the
fill
property).
Example line01
below
specifies the coordinates of the five lines in the user coordinate system
established by the
viewBox
attribute on the
svg
element. The
lines have different thicknesses.


Example line01 - lines expressed in user coordinates

fill="none" stroke="blue" stroke-width="2" />

stroke-width="5" />
stroke-width="10" />
stroke-width="15" />
stroke-width="20" />
stroke-width="25" />


Example line01
View this example as SVG (SVG-enabled browsers only)
10.6. The
‘polyline’
element
The
polyline
element defines a set of connected straight
line segments. Typically,
polyline
elements define open
shapes.
polyline
Categories:
Graphics element
renderable element
shape 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
clipPath
marker
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
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
pathLength
points
DOM Interfaces:
SVGPolylineElement
Attribute definitions:
Name
Value
Initial value
Animatable
points

(none)
yes
where:


+ ]#
The points that make up the polyline. All coordinate
values are in the user coordinate system.
If an odd number of coordinates is provided, then the element is in
error, with the same user agent behavior as occurs with an incorrectly
specified
path
element. In such error cases the user agent will drop
the last, odd coordinate and otherwise render the shape.
The initial value, (none), indicates that the polyline element
is valid but does not render.
A future specification may convert the
points
attribute to a geometric property.
Currently, it can only be specified via an element attribute, and not CSS.
Mathematically, a
polyline
element can be mapped to an
equivalent
path
element as follows:
perform an absolute
moveto
operation to the first coordinate pair in the list of points
for each subsequent coordinate pair, perform an absolute
lineto
operation to that
coordinate pair.
Example polyline01
below specifies a polyline in the user coordinate system established by the
viewBox
attribute on the
svg
element.


Example polyline01 - increasingly larger bars

fill="none" stroke="blue" stroke-width="2" />

points="50,375
150,375 150,325 250,325 250,375
350,375 350,250 450,250 450,375
550,375 550,175 650,175 650,375
750,375 750,100 850,100 850,375
950,375 950,25 1050,25 1050,375
1150,375" />

Example polyline01
View this example as SVG (SVG-enabled browsers only)
10.7. The
‘polygon’
element
The
polygon
element defines a closed shape consisting of a
set of connected straight line segments.
polygon
Categories:
Graphics element
renderable element
shape 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
clipPath
marker
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
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
pathLength
points
DOM Interfaces:
SVGPolygonElement
Attribute definitions:
Name
Value
Initial value
Animatable
points

(none)
yes
The points that make up the polygon. All coordinate
values are in the user coordinate system.
If an odd number of coordinates is provided, then the element is in
error, with the same user agent behavior as occurs with an incorrectly
specified
path
element.
The initial value, (none), indicates that the polygon element
is valid, but does not render.
A future specification may convert the
points
attribute to a geometric property.
Currently, it can only be specified via an element attribute, and not CSS.
Mathematically, a
polygon
element can be mapped to an
equivalent
path
element as follows:
perform an absolute
moveto
operation to the first coordinate pair in the list of points
for each subsequent coordinate pair, perform an absolute
lineto
operation to that
coordinate pair
perform a
closepath
command
Example
polygon01
below specifies two polygons (a star and a hexagon) in
the user coordinate system established by the
viewBox
attribute
on the
svg
element.


Example polygon01 - star and hexagon

fill="none" stroke="blue" stroke-width="2" />

points="350,75 379,161 469,161 397,215
423,301 350,250 277,301 303,215
231,161 321,161" />
points="850,75 958,137.5 958,262.5
850,325 742,262.6 742,137.5" />

Example polygon01
View this example as SVG (SVG-enabled browsers only)
10.8. DOM interfaces
10.8.1. Interface SVGRectElement
An
SVGRectElement
object represents a
rect
element in the DOM.
Exposed
=Window]
interface
SVGRectElement
SVGGeometryElement
SameObject
] readonly attribute
SVGAnimatedLength
SameObject
] readonly attribute
SVGAnimatedLength
SameObject
] readonly attribute
SVGAnimatedLength
width
SameObject
] readonly attribute
SVGAnimatedLength
height
SameObject
] readonly attribute
SVGAnimatedLength
rx
SameObject
] readonly attribute
SVGAnimatedLength
ry
};
The
width
height
rx
and
ry
IDL attributes
reflect
the computed values of the
width
height
rx
and
ry
properties and their corresponding presentation attributes,
respectively.
10.8.2. Interface SVGCircleElement
An
SVGCircleElement
object represents a
circle
element in the DOM.
Exposed
=Window]
interface
SVGCircleElement
SVGGeometryElement
SameObject
] readonly attribute
SVGAnimatedLength
cx
SameObject
] readonly attribute
SVGAnimatedLength
cy
SameObject
] readonly attribute
SVGAnimatedLength
};
The
cx
cy
and
IDL attributes
reflect
the computed values of the
cx
cy
and
properties and their corresponding presentation attributes,
respectively.
10.8.3. Interface SVGEllipseElement
An
SVGEllipseElement
object represents a
ellipse
element in the DOM.
Exposed
=Window]
interface
SVGEllipseElement
SVGGeometryElement
SameObject
] readonly attribute
SVGAnimatedLength
cx
SameObject
] readonly attribute
SVGAnimatedLength
cy
SameObject
] readonly attribute
SVGAnimatedLength
rx
SameObject
] readonly attribute
SVGAnimatedLength
ry
};
The
cx
cy
rx
and
ry
IDL attributes
reflect
the computed values of the
cx
cy
rx
and
ry
properties
and their corresponding presentation attributes,
respectively.
10.8.4. Interface SVGLineElement
The
SVGLineElement
interface corresponds to the
line
element.
Exposed
=Window]
interface
SVGLineElement
SVGGeometryElement
SameObject
] readonly attribute
SVGAnimatedLength
x1
SameObject
] readonly attribute
SVGAnimatedLength
y1
SameObject
] readonly attribute
SVGAnimatedLength
x2
SameObject
] readonly attribute
SVGAnimatedLength
y2
};
The
x1
y1
x2
and
y2
IDL attributes
reflect
the
x1
y1
x2
and
y2
content attributes, respectively
10.8.5. Mixin SVGAnimatedPoints
The
SVGAnimatedPoints
interface is used to
reflect
points
attribute on a
polygon
or
polyline
element. It is mixed in to the
SVGPolygonElement
and
SVGPolylineElement
interfaces.
interface mixin
SVGAnimatedPoints
SameObject
] readonly attribute
SVGPointList
points
SameObject
] readonly attribute
SVGPointList
animatedPoints
};
The
points
IDL attribute
represents the current non-animated value of the reflected attribute.
On getting
points
an
SVGPointList
object is returned that reflects the base
value of the reflected attribute.
The
animatedPoints
IDL attribute
represents the current non-animated value of the reflected attribute.
On getting
animatedPoints
an
SVGPointList
object is returned that reflects the animated
value of the reflected attribute.
The objects returned from
points
and
animatedPoints
must be distinct, even
if there is no animation currently affecting the attribute.
10.8.6. Interface SVGPointList
The
SVGPointList
interface is a
list interface
whose
elements are
DOMPoint
objects. An
SVGPointList
object represents a list of points.
Exposed
=Window]
interface
SVGPointList

readonly attribute unsigned long
length
readonly attribute unsigned long
numberOfItems

undefined
clear
();
DOMPoint
initialize
DOMPoint
newItem);
getter
DOMPoint
getItem
(unsigned long index);
DOMPoint
insertItemBefore
DOMPoint
newItem, unsigned long index);
DOMPoint
replaceItem
DOMPoint
newItem, unsigned long index);
DOMPoint
removeItem
(unsigned long index);
DOMPoint
appendItem
DOMPoint
newItem);
setter
undefined (unsigned long index,
DOMPoint
newItem);
};
The behavior of all of the interface members of
SVGPointList
are
defined in
List interfaces
This specification imposes additional requirements on the behaviour of
DOMPoint
objects beyond those described in the
Geometry Interfaces
specification, so that they can be used to reflect
points
attributes.
Every
DOMPoint
object operates in one of four modes. It
can:
reflect an element of the base value
of a
reflected
animatable
attribute (being exposed through the methods on the
points
member of
an
SVGAnimatedPoints
),
reflect an element of the animated value
of a
reflected
animatable
attribute (being exposed through the methods on the
animatedPoints
member of
an
SVGAnimatedPoints
),
represent the current translation
of a given
svg
element
(being exposed through the
currentTranslate
member on
SVGSVGElement
), or
be detached
, which is the case for
DOMPoint
objects created
using their constructor or with
createSVGPoint
DOMPoint
object can be
associated
with a particular element. The associated element is used to
determine which element's content attribute to update if the object
reflects
an attribute. Unless otherwise described, a
DOMPoint
object is not
associated with any element.
DOMPoint
object can be designated as
read only
which means that attempts to modify the object will result in an exception
being thrown. When assigning to a read only
DOMPoint
's
or
IDL attribute, a
NoModificationAllowedError
must be
thrown
instead of updating the internal coordinate value.
Note that this applies only to the read-write
DOMPoint
interface; the
DOMPointReadOnly
interface, which is not used for reflecting
the
points
attribute, will already throw an exception if
an attempt is made to modify it.
When assigning to a writable
DOMPoint
's
or
IDL attribute, the following steps are run after updating
the internal coordinate value:
If the
DOMPoint
reflects an element of the
base value
of a
reflected
attribute, then
reserialize
the reflected attribute using the
SVGPointList
that reflects
the attribute's base value.
Otherwise, if the
DOMPoint
represents
the current translation
of an
svg
element and that
element is the
outermost svg element
, then:
Let [
be the 2x3 matrix that represents the document's magnification and panning
transform.
Let
and
be the x and y coordinates of the
DOMPoint
object, respectively.
Set the document's magnification and panning transform to
0 0
].
10.8.7. Interface SVGPolylineElement
An
SVGPolylineElement
object represents a
polyline
element in the DOM.
Exposed
=Window]
interface
SVGPolylineElement
SVGGeometryElement
};
SVGPolylineElement
includes
SVGAnimatedPoints
10.8.8. Interface SVGPolygonElement
An
SVGPolygonElement
object represents a
polygon
element in the DOM.
Exposed
=Window]
interface
SVGPolygonElement
SVGGeometryElement
};
SVGPolygonElement
includes
SVGAnimatedPoints
Chapter 11: Text
11.1. Introduction
Text that is to be rendered as part of an SVG document fragment is
specified using the
text
element. The text within a
text
element can be rendered:
pre-formatted (with limited line wrapping),
auto-wrapped (if a
content area
is provided),
on a path (if a
textPath
element is provided).
The section
Text layout
gives an
introduction to text layout. It is followed by sections covering
content areas
and
the
algorithm
for
laying out text within a
content area
The specialized layout rules corresponding to text that is
pre-formatted
auto-wrapped
, and
on a path
are then addressed in individual sections.
Rules for text layout in SVG 1.1 are mostly defined within the SVG
1.1 specification. The rules mirror to a large extent those found
in CSS. In SVG 2, the dependence on CSS is more explicit. In
practice the resulting layout is the same. The change to directly
relying on CSS specifications simplifies the SVG specification
while making it more obvious that rendering agents can use the
same code to render both text in HTML and in SVG. In particular,
SVG 2 auto-wrapped text is based on CSS text layout.
SVG's
text
elements are rendered like other graphics
elements. Thus,
coordinate system
transformations
painting
clipping
and
masking
features apply to
text
elements in the same way as they apply to
shapes
such as
paths
and
rectangles
SVG text supports advanced typographic features including:
choice of typeface,
use of discretionary, historical, or stylistic ligatures,
text decorations (underlining, over-lining, etc.).
SVG text supports international text processing needs such as:
horizontal and vertical orientation of text,
left-to-right or bidirectional text (i.e., languages
which intermix right-to-left and left-to-right text, such as
Arabic and Hebrew),
complex text layout where: there is not always a one-to-one
correspondence between characters and glyphs, characters
may change shape depending on location (e.g. Arabic), and
characters may be reordered or combined depending on context
(e.g. Devanagari),
glyph alignment to different baselines (
alphabetic
for
western scripts,
hanging
for northern Indic scripts,
and
ideographic
for far-eastern scripts).
Multi-language SVG content is possible by
substituting different
text strings based on the user's preferred language
The characters to be drawn are expressed as
character data
([
xml
],
section 2.4) inside the
text
element. As a result:
Text data in SVG content is readily accessible to the visually
impaired (see
Support
).
In many viewing scenarios, the user will be able to search for
and select text strings and copy selected text strings to the
system clipboard (see
Text
selection and clipboard operations
).
XML-compatible Web search engines will find text strings in
SVG content with no additional effort over what they need to
do to find text strings in other XML documents.
For accessibility reasons, it is recommended that text that is
included in a document have appropriate semantic markup to
indicate its function.
For example,
a text element that provides a visible label for part of a diagram
should have an
id
that is referenced by
an
aria-labelledby
attribute on the relevant group or path element.
See
SVG
accessibility guidelines
for more information.
11.1.1. Definitions
character
A character is an atomic unit of text as defined in XML
XML
].
Essentially, a Unicode code point.
A character may be a control instruction (such as a tab, carriage return, or line feed),
a renderable mark (letter, digit, punctuation or other symbol),
or a modifier (such as a combining accent).
addressable character
character
that is addressable by text positioning
attributes and SVG DOM text methods.

Characters discarded during layout such as
collapsed
white space characters
are not addressable, neither are characters
within an element with a value of
none
for
the
display
property.

Addressable characters are addressed by their index. Indexes are
determined prior to applying any
text-transform
conversions, as described for the methods in the
SVGTextContentElement
interface.

There are two methods to map an index to a character; the choice of
which to use depends on purpose:
For the purposes of mapping text positioning attributes, the
index is measured in Unicode code points (thus a 'u'
followed by the combining diaeresis ' ̈' is counted as two
characters while the precomposed character 'ü' is counted as
one character).
For the purposes of SVG DOM text methods, the index is
measured in UTF-16 code units (thus, a single Unicode code
point above U+FFFF will map to two addressable characters as
a UTF-16 code unit consists of 16 bits).
The different methods are backwards compatible with SVG
1.1. The use of UTF-16 code units for SVG DOM text methods is
required from the definition of DOMString in the DOM 2
specification.
The SVG working group is interested in implementer feedback on
the possibility of using grapheme clusters as defined by the
Unicode Standard Annex #29 to replace Unicode code points in
mapping text positioning attributes. Note, the use of the
CSS
typographic character
is not appropriate as what
constitutes a character can depend on context (line-breaking,
word-breaking, etc.).
If support for CSS generated-content text is introduced in the future,
it would be included in the array of addressable characters.
typographic character
A unit of a writing system— such as a Latin alphabetic letter
(including its diacritics), Hangul syllable, Chinese ideographic
character, Myanmar syllable cluster— that is indivisible with
respect to a particular typographic operation (line-breaking,
first-letter effects, tracking, justification, vertical
arrangement, etc.). For the normative definition and the
relationship between this and a Unicode grapheme cluster, see
CSS
Text Module Level 3
([
css-text-3
]).
font
A font represents an organized collection of
glyphs
in
which the various glyph representations will share a particular
appearance or styling.
glyph
A glyph represents a unit of rendered content within a
font
. Often, there is a one-to-one correspondence between
characters to be drawn and corresponding glyphs (e.g., usually
the character "A" is rendered using a single glyph), but other
times multiple glyphs are used to render a single character
(e.g., characters with accents) or a single glyph can be used to render
multiple characters (e.g., ligatures). Typically, a glyph is
defined by one or more
shapes
such as
path
, possibly with additional
information such as rendering hints that help a font engine to
produce legible text in small sizes.
text content element
A text content element is an SVG element that causes a text
string to be rendered onto the canvas. The SVG text content
elements are:
text
textPath
and
tspan
text content child element
A text content child element is a
text content element
that is allowed as a descendant of another
text content element
. In SVG the text content child elements are:
textPath
and
tspan
text content block element
A text content block element is a
text content element
that serves as a standalone element for a unit of text, and
which may optionally contain certain child
text content elements
(e.g.
‘tspan’
).
SVG 2 defines a single text content block element:
text
content area
The area in which the text is normally laid out. This is
equivalent to the
CSS
content area
. The actual region where text layout occurs may
be smaller due to padding and/or exclusions.
wrapping context
One or more regions (shapes) to be excluded from the content
area during text layout. This is the same as the
CSS wrapping context
wrapping area
The area in which the text is laid out after subtracting any
padding or exclude areas (
wrapping context
). This is the
same as the
CSS wrapping area
line box
The rectangular area containing all the content used to layout a single line of text.
This is the same as the
CSS line box
Although various CSS 3 text layout specs use the term,
none current establish a formal definition.
The link is therefore to CSS 2.1,
and
an issue has been filed with CSS WG
inline-base direction
The primary direction in which content is ordered within a line
or part of a line of text. It defines the
start
and
end
sides of a line or part of a line of text (relevant,
for example to how the
text-anchor
property is
applied). It is determined by the
direction
property.
(Note: the ordering of characters in a line of text is primary
controlled by the Unicode bidi algorithm and not the inline-base
direction.)
block-flow direction
The direction in which
line boxes
are stacked. It is
determined by the
writing-mode
property.
alignment point
The point on a typographic character that should be aligned with
the
current text position
. It is determined by the glyph
cell metrics and may depend on the script and
inline-base direction
current text position
The point in the current user space where the
alignment point
of the next typographic character to be rendered
should be placed.
text chunk
An independent block of text in which all characters are
positioned together. Each new absolute positioning adjustment
(due to an
or
attribute, or
forced line break) creates a new
text chunk
. Ligature
substitution and bidi-reordering only occur within a
text chunk
Text chunks
are only relevant to pre-formatted
text.
white space characters
The following characters are considered white space characters:
U+0009 CHARACTER TABULATION,
U+000C FORM FEED (FF),
U+000D CARRIAGE RETURN (CR),
U+000A LINE FEED (LF) and
U+0020 SPACE.
11.1.2. Fonts and glyphs
A font consists of a collection of glyphs together with other
information (collectively, the font tables) necessary to use those
glyphs to present characters on some visual medium. The
combination of the collection of glyphs and the font tables is
called the
font data
A font may supply substitution and positioning tables that
can be used by a formatter (text shaper) to re-order, combine and
position a sequence of glyphs to form one or more composite
glyphs. The combining may be as simple as a ligature, or as
complex as an indic syllable which combines, usually with some
re-ordering, multiple consonants and vowel glyphs. The tables may
be language dependent, allowing the use of language appropriate
letter forms.
When a glyph, simple or composite, represents an indivisible unit
for typesetting purposes, it is know as a
typographic character
Ligatures are an important feature of advance text layout. Some
ligatures are discretionary while others (e.g. in Arabic) are
required. The following explicit rules apply to ligature
formation:
Ligature formation should not be enabled when characters are
in different DOM text nodes;
thus, characters separated by markup should not use ligatures.
Ligature formation should not be enabled when characters are
in different
text chunks
Discretionary ligatures should not be used when the spacing
between two characters is not the same as the
default space (e.g. when
letter-spacing
has a
non-default value, or
text-align
has a value of
justify
and
text-justify
has a value of
distribute
).
(See
CSS
Text Module Level 3
([
css-text-3
]).
SVG attributes such as
dx
textLength
and
spacing
(in
textPath
) that may
reposition
typographic characters
do not break discretionary
ligatures.
If discretionary ligatures are not desired they can be turned
off by using the
font-variant-ligatures
property.
For OpenType fonts, discretionary ligatures include those enabled
by the liga, clig, dlig, hlig, and cala features; required ligatures
are found in the rlig feature.
SVG 2 Requirement:
Include explicit support for Web Open Font Format (WOFF).
Resolution:
We will mandate WOFF support in SVG 2.
Purpose:
To allow access to full OpenType features for internationalization and advanced typography.
Owner:
Chris (no action)
Status:
Done
Proper text rendering may depend on using the same font as used
during authoring. For this reason SVG requires support for
downloadable fonts as defined in the
Font
Resources
section of the
CSS Fonts
Module
. In particular, support for the Web Open Font Format
WOFF
] is required.
New in SVG 2, WOFF allows authors to provide the fonts needed to
properly render their content. This includes ensuring that the
fonts have the proper OpenType tables to support complex scripts,
discretionary ligatures, swashes, old-style numbers, and so
on. WOFF also allows the fonts to be compressed, subsetted, and
include licensing information.
11.1.3. Glyph metrics and layout
Glyph selection and positioning is normally handled according to
the rules of CSS. In some cases, however, the final layout of text
in SVG requires knowledge of the geometry properties of individual
glyphs.
The geometric font characteristics are expressed in a coordinate
system based on the EM box. (The EM is a relative measure of the
height of the glyphs in the font.) The box 1 EM high and 1 EM
wide is called the
design space
. This space is given a
geometric coordinates by sub-dividing the EM into a number
of
units per em
Units per em is a font characteristic. A typical value
for units per em is 1000 or 2048.
The coordinate space of the EM box is called the
design space
coordinate system
. For scalable fonts, the curves and lines
that are used to draw a glyph are represented using this
coordinate system.
Most often, the (0,0) point in this coordinate system is
positioned on the left edge of the EM box, but not at the bottom
left corner. The Y coordinate of the bottom of a roman capital
letter is usually zero. The descenders on lowercase roman
letters have negative coordinate values.
An 'M' inside an Em box (blue square). The 'M' sits on the
baseline (blue line). The origin of the coordinate system is
shown by the small black circle.
SVG assumes that the font tables will provide at least three font
characteristics: an ascent, a descent and a set of
baseline-tables. The ascent is the distance to the top of the EM
box from the (0,0) point of the font; the descent is the distance
to the bottom of the EM box from the (0.0) point of the font. The
baseline-table is explained below.
Within an OpenType font ([
OPENTYPE
]),
for horizontal writing-modes,
the ascent and descent are given by the sTypoAscender and
sTypoDescender entries in the OS/2 table. For vertical writing-modes,
the descent (the distance, in this case from the (0,0) point to the
left edge of the glyph) is normally zero because the (0,0) point is on
the left edge. The ascent for vertical writing-modes is either 1 em or
is specified by the ideographic top baseline value in the OpenType
Base table for vertical writing-modes.
Glyphs are positioned relative to a particular point on each glyph
known as the
alignment point
. For horizontal
writing-modes, the glyphs'
alignment points
are vertically
aligned while for vertical writing-modes, they are horizontally
aligned. The position of the
alignment point
depends on the
script. For example, Western glyphs are aligned at the bottom of
capital letters, northern Indic glyphs are aligned at the top
of a horizontal stroke near the top of the glyphs, and far-eastern
glyphs are aligned either at the bottom or center of the glyph.
Within a script and within a line of text having a single
font-size, the sequence of alignment points defines, in the
inline-base direction
, a geometric line called a
baseline
. Western and most other alphabetic and
syllabic glyphs are aligned to an "alphabetic" baseline, the
northern Indic glyphs are aligned to a "hanging" baseline and the
far-eastern glyphs are aligned to an "ideographic" baseline.
Example baselines (red lines) in three different scripts. From
left to right: alphabetic, hanging, ideographic. The EM box is
shown in blue for the ideographic script.
As glyphs are sequentially placed along a baseline, the
alignment point
of a glyph is typically positioned at the
current text position
(some properties such as
vertical-align
may alter the positioning). After each
glyph is placed, the
current text position
is advanced by
the glyph's
advance
value (typically the width for
horizontal text or height for vertical text) with any correction
for kerning or other spacing adjustment as well as for new lines
in pre-formatted or auto-wrapped text. The initial and final
current text positions are used for alignment (e.g. when
the
text-anchor
value is either 'middle' or 'end'). The
glyph's advance is needed when placing text along a path.
Example of font metrics. The blue boxes show the geometric
boxes for the three glyphs. The labeled small circles show the
current text position
before glyph placement. The
small square shows the final
current text position
after placing the last glyph. Note that the left side of
the 'a' glyph's box is not aligned with the right side of
the 'V' glyph's box due to kerning.
If a glyph does not provide explicit advance values corresponding
to the current glyph orientation, then an appropriate
approximation should be used. For vertical text, a suggested
approximation is the
em
size.
The initial
current text position
is established by the
and
attributes on the
text
element or first rendered
tspan
element for
pre-formatted text, or auto-wrapped text when the
content area
is determined by the
inline-size
property. For
other auto-wrapped text, the initial
current text position
is determined by the position of the first rendered glyph after
applying the CSS line wrapping algorithm.
baseline-table
specifies the position of one or more
baselines in the design space coordinate system. The function of
the baseline table is to facilitate the alignment of different
scripts with respect to each other when they are mixed on the same
text line. Because the desired relative alignments may depend on
which script is dominant in a line (or block), there may be a
different baseline table for each script. In addition, different
alignment positions are needed for horizontal and vertical writing
modes. Therefore, the font may have a set of baseline tables:
typically, one or more for horizontal writing-modes and zero or
more for vertical writing-modes.
Some fonts may not have values for the baseline tables. Heuristics
are suggested for approximating the baseline tables in
CSS
Inline Layout Module Level 3
[css-inline-3]
when a given font does not supply baseline tables.
When a different font (or change in font size) is specified in the
middle of a run of text, the
dominant baseline
determines the baseline used to align glyphs in the new font (new
size) to those in the previous font. The
dominant-baseline
property is used to set the dominant
baseline.
Alignment between an object relative to its parent is determined
by the
alignment baseline
. It is normally the same
baseline as the dominant baseline but by using the shorthand
vertical-align
property (preferred) or the longhand
alignment-baseline
another baseline can be chosen.
The dominant baseline can be temporarily shifted (as needed
for superscripts or subscripts) by using either the shorthand
vertical-align
property (preferred) or the longhand
baseline-shift
property. Note that shifts can be
nested, each shift added to the previous shift.
Examples of using the 'vertical-align' property.

Left: 'vertical-align:mathematical'
('alignment-baseline:mathematical') is applied to
the
tspan
containing '[z]'. The light-blue line shows
the position of the mathematical baseline.

Right: 'vertical-align:super' ('baseline-shift:super') applied
to the
tspan
containing '2'. The light-blue lines
indicate the shift in baseline.
SVG further assumes that for each glyph in the font data for a
font, there are two width values, two alignment-baselines and two
alignment points, one each for horizontal writing-modes and the
other for vertical writing-modes. (Even though it is specified as
a width, for vertical writing-modes the width is used in the
vertical direction.) The
inline-base direction
position of the alignment point is on the start-edge of the glyph.
Additional information on baselines can be found in the
CSS
Inline Layout Module Level 3
specification.
css-inline-3
(Also see:
CSS
Writing Modes Level 3
specification.
css-writing-modes-3
])
SVG 2 Requirement:
Support text aligned to different baselines.
Resolution:
SVG 2 will support glyphs being aligned to different baselines, perhaps by using existing or improved CSS properties.
Purpose:
To allow glyphs in horizontal text to have different vertical alignments for stylistic effects.
Owner:
Chris (no action)
Status:
Done
A single line of text is laid out inside a
line box
Multi-line text is produced by stacking these boxes. The height of
line box
is determined by finding the maximum ascent and
the maximum descent of all the glyphs in a line of text after
applying the effect of the
line-height
property. The
width of a
line box
is normally the width of the containing
text block. In SVG, when the containing text block does not have a
fixed geometry (as with pre-formatted text), the
line box
tightly wraps the glyph boxes within the box.
Example of determining the height of a
line box

First each glyph box (small light-blue boxes) is extended
vertically above and below according to the
line-height
property. In this case the
line-height
property is
125%. The larger glyphs have a
font-size
of 96px so
their extra height is 24px (25% of 96px). The extra height is
evenly divided above and below resulting in the red boxes. (For
clarity, all glyphs in the same inline element have been grouped
together).
The final
line box
(large light-blue box) is then found
using the maximum extents of the red boxes above and below the
baseline.
In order to support various international writing systems,
line boxes
may be orientated in a horizontal or vertical direction.
Text within a vertical
line box
flows from top to bottom.
Text within a horizontal
line box
may flow left-to-right
(e.g., modern Latin scripts), right-to-left (e.g., Hebrew or
Arabic), or a mixture of left-to-right and right-to-left
(bidirectional text).
The processing model for bidirectional text is as follows:
The
user agent processes the characters which are provided in
logical order
(i.e., the order the characters appear in
the original document).
The user agent excludes non-rendered elements
and
collapses white space
The user agent determines
the set of independent blocks within each of which it should apply
the Unicode bidirectional algorithm.
Each
text chunk
represents an independent block of text.
Any change in glyph
orientation due to processing of the
text-orientation
or obsoleted
glyph-orientation-vertical
properties
will start a new independent
blocks of text for bi-directional purposes.
After processing the Unicode bidirectional
algorithm and properties
direction
and
unicode-bidi
on each of the independent text blocks, the
user agent will have a potentially re-ordered list of characters
which are now in left-to-right rendering order. Simultaneous with
re-ordering of the characters, the
dx
dy
, and
rotate
attributes on the
text
and
tspan
elements are also re-ordered to
maintain the original correspondence between characters and
attribute values.
While kerning or ligature processing might be
font-specific, the preferred model is that kerning and ligature
processing occurs between combinations of characters or glyphs
after the characters have been re-ordered.
The orientation of
line boxes
as well as the direction in
which they are stacked (
block-flow direction
) is determined
by the
writing-mode
property. For horizontal text
writing-mode
value
horizontal-tb
line boxes
are stacked from top to bottom. For vertical text,
line boxes
are stacked from right-to-left (
writing-mode
value
vertical-rl
) or left-to-right
writing-mode
value
vertical-lr
).
11.2. The
‘text’
and
‘tspan’
elements
The
text
element defines a graphics element consisting of
text. The
tspan
element within a
text
or another
tspan
element, allows one to switch the style and/or
adjust the position of the rendered text inside the
tspan
element relative to the parent element.
The character data within the
text
and
tspan
elements, along with relevant attributes and properties, and
character-to-glyph mapping tables within the font itself, define
the glyphs to be rendered. The attributes and properties on
the
text
and
tspan
elements indicate such things
as the writing direction, font specification, and painting
attributes which describe how exactly to render the
characters. Subsequent sections of this chapter describe the
relevant text-specific attributes and properties.
Since
text
and
tspan
elements are rendered using
the same rendering methods as other graphics elements, all of the
same
painting
features that apply to
shapes
such as
paths
and
rectangles
also apply to
text
and
tspan
elements,
except for
markers
In addition,
coordinate system transformations
clipping
, and
masking
can be applied
to the
text
element as a whole.
In CSS terms, the
text
element acts as a block
element. The
tspan
textPath
, and
elements that are descended from
text content elements
act as
inline elements.
It is possible to apply a gradient, pattern, clipping path, mask
or filter to text. When one of these facilities is applied to text
and keyword
'objectBoundingBox'
is
used (see
Object bounding box
units
) to specify a graphical effect relative to the "object
bounding box", then the object bounding box units are computed
relative to the entire
text
element in all cases, even
when different effects are applied to different
tspan
or
textPath
elements within the same
text
element.
The
text
element renders its first glyph (after
bidirectionality
reordering) at the initial
current text position
(with
possible adjustments due to the value of the
text-anchor
property or the
text-align
property).
For pre-formatted text and for auto-wrapped text where the
content area
is determined by the
inline-size
property, the initial
current text position
is determined by the
and
values of the
text
or
tspan
element which contains the first rendered character.

For auto-wrapped text in a shape or text on a path see
the
Auto-wrapped text
or
Text on a path
sections,
respectively, to determine the initial
current text position

After the glyph(s) corresponding to the given character is (are)
rendered, the current text position is updated for the next
character. In the simplest case, the new current text position is
the previous current text position plus the glyphs' advance value
(horizontal or vertical). See
text layout
for a description
of glyph placement and glyph advance.
The text string
Hello, out there!
is rendered onto the
canvas using the Verdana font family with the glyphs filled
with the color blue.

font-family="Verdana" font-size="64" fill="blue" >
Hello, out there!

tspan
is used to change the styling of the word
not

You are
not
a banana.

Two
tspan
elements are repositioned horizontally and
vertically using the
and
attributes. Because all the text is within a single
text
element, a user will be able to select through all
the text and copy it to the system clipboard in user agents that
support
text selection and
clipboard operations

But you

are


a peach!

text
Categories:
Graphics element
renderable element
text content element
Content model:
Any number of the following elements or character data, in any order:
animation elements
animate
animateMotion
animateTransform
set
descriptive elements
desc
title
metadata
paint server elements
linearGradient
radialGradient
pattern
text content child elements
tspan
textPath
clipPath
marker
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
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
lengthAdjust
dx
dy
rotate
textLength
DOM Interfaces:
SVGTextElement
SVG 2 Requirement:
Allow transforms on
tspan
Resolution:
SVG 2 will allow transforms on
‘tspan’
Purpose:
Align with other elements such as
which already allow transforms.
Owner:
Cameron (no action)
Status:
Done
This decision was reversed. See
GitHub Issue
210
. CSS/HTML does not allow transforms on inline elements
and no renderer supports transforms on the
element
when inline (in both SVG and HTML).
tspan
Categories:
Graphics element
renderable element
text content element
text content child element
Content model:
Any number of the following elements or character data, in any order:
descriptive elements
desc
title
metadata
paint server elements
linearGradient
radialGradient
pattern
animate
script
set
style
tspan
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
dx
dy
rotate
textLength
lengthAdjust
DOM Interfaces:
SVGTSpanElement
11.2.1. Attributes
Name
Value
Initial value
Animatable
[ [


]+ ]#
0 for
text
(none) for
tspan
yes
If a single

is
provided, then the value represents the new absolute X (Y)
coordinate for the
current text position
for rendering
the glyphs that correspond to the first character within this
element or any of its descendants.
If a comma- or space-separated list of

s is provided, then the values represent
new absolute X (Y) coordinates for the
current text position
for rendering the glyphs corresponding to each of
the first
addressable characters
within this element or any
of its descendants.
If more

s are provided than characters,
then the extra

s will have no effect on
glyph positioning.
If more characters exist than

s,
or if the attribute is not specified on a
tspan
then for each additional character:
if an ancestor
text
or
tspan
element
specifies an absolute X (Y) coordinate for the given character
via an
‘x’
‘y’
) attribute
(nearest ancestor has precedence), then that
absolute X (Y) coordinate is used as the starting X (Y)
coordinate for that character, else
the starting X (Y) coordinate for rendering the glyphs
corresponding to the given character is the X (Y) coordinate
of the resulting
current text position
from the most
recently rendered glyph for the current
text
element.
In SVG 2, the
text
and
tspan
and
attributes are not presentation attributes
and cannot be set via CSS. This may change in a future version
of SVG.
Name
Value
Initial value
Animatable
dx
dy
[ [


]+ ]#
(none)
yes
If a single

is provided, this value
represents the new relative X (Y) coordinate for the
current text position
for rendering the glyphs corresponding to
the first character within this element or any of its
descendants. The
current text position
is shifted along
the x-axis (y-axis) of the current user coordinate system
by

before the first character's glyphs
are rendered.
If a comma- or space-separated list of

s is provided, then the values represent
incremental shifts along the x-axis (y-axis) for
the
current text position
before rendering the glyphs
corresponding to the first
addressable characters
within this
element or any of its descendants. Thus, before the glyphs are
rendered corresponding to each character, the
current text position
resulting from drawing the glyphs for the
previous character within the current
text
element is
shifted along the x-axis (y-axis) of the current user
coordinate system by

If more

s are provided than characters,
then any extra

s will have no effect on
glyph positioning.
If more characters exist than

s,
or if the attribute is not specified,
then for each additional character:
if an ancestor
text
or
tspan
element
specifies a relative X (Y) coordinate for the given character
via a
‘dx’
‘dy’
) attribute
(nearest ancestor has precedence), then
the
current text position
is shifted along the x-axis
(y-axis) of the current user coordinate system by that amount, else
no extra shift along the x-axis (y-axis) occurs.
Name
Value
Initial value
Animatable
rotate

+ ]#
(none)
yes (non-additive).
The supplemental rotation, in degrees, about the
current text position
that will be applied to all of the glyphs
corresponding to each character within this element.
If a comma- or space-separated list of

is provided, then the first

represents
the supplemental rotation for the glyphs corresponding to the
first character within this element or any of its descendants,
the second

represents the supplemental
rotation for the glyphs that correspond to the second
character, and so on.
If more

s are provided than there are
characters, then the extra

s will be
ignored.
If more characters are provided than

s,
then for each of these extra characters the rotation value
specified by the last number must be used.
If the attribute is not specified and if an ancestor of a
tspan
element specifies a supplemental rotation for a
given character via a
rotate
attribute
(nearest ancestor has precedence), then the
given supplemental rotation is applied to the given character.
If there are more
characters than

s specified in the
ancestor's
rotate
attribute, then for each of these
extra characters the rotation value specified by the last
number must be used.
This supplemental rotation has no impact on the rules by
which
current text position
is modified as glyphs get
rendered and is supplemental to any rotation due to
text on a path
and
to
text-orientation
glyph-orientation-horizontal
or
glyph-orientation-vertical
Name
Value
Initial value
Animatable
textLength


See below
yes
The author's computation of the total sum of all of the
advance values that correspond to character data within this
element, including the advance value on the glyph (horizontal
or vertical), the effect of properties
letter-spacing
and
word-spacing
and adjustments due to attributes
dx
and
dy
on this
text
or
tspan
element or any descendants. This value is
used to calibrate the user agent's own calculations with that
of the author.
The purpose of this attribute is to allow the author to
achieve exact alignment, in visual rendering order after
any bidirectional
reordering, for the first and last rendered glyphs that
correspond to this element; thus, for the last rendered
character (in visual rendering order after
any bidirectional
reordering), any supplemental inter-character spacing
beyond normal glyph advances are ignored (in most cases) when
the user agent determines the appropriate amount to
expand/compress the text string to fit within a length of
textLength
If attribute
textLength
is specified on a given
element and also specified on an ancestor, the adjustments on
all character data within this element are controlled by the
value of
textLength
on this element exclusively, with
the possible side-effect that the adjustment ratio for the
contents of this element might be different than the
adjustment ratio used for other content that shares the same
ancestor. The user agent must assume that the total advance
values for the other content within that ancestor is the
difference between the advance value on that ancestor and the
advance value for this element.
This attribute is not intended for use to obtain effects such
as shrinking or expanding text.
A negative value is an error
(see
Error
processing
).
The
textLength
attribute is only applied when the
wrapping area
is not defined by the
shape-inside
or
the
inline-size
properties. It is also not applied for
any
text
or
tspan
element that has forced line breaks
(due to a
white-space
value of
pre
or
pre-line
).
If the attribute is not specified anywhere within a
text
element, the effect is as if the author's
computation exactly matched the value calculated by the user
agent; thus, no advance adjustments are made.
For the purpose of
reflecting
the attribute in the DOM,
the
initial value
is the current user-agent calculated length,
expressed in implicit
user units
Name
Value
Initial value
Animatable
lengthAdjust
spacing | spacingAndGlyphs
spacing
yes
spacing
Indicates that only the advance values are adjusted. The
glyphs themselves are not stretched or compressed.
spacingAndGlyphs
Indicates that the advance values are adjusted and the
glyphs themselves stretched or compressed in one axis (i.e.,
a direction parallel to the
inline-base direction
).
The user agent is required to achieve correct start and end
positions for the text strings, but the locations of
intermediate glyphs are not predictable because user agents
might employ advanced algorithms to stretch or compress text
strings in order to balance correct start and end positioning
with optimal typography.
Note that, for a text string that contains
characters, the adjustments to the advance values often occur
only for
−1 characters (see description of
attribute
textLength
), whereas stretching or
compressing of the glyphs will be applied to all
characters.
11.2.2. Notes on 'x', 'y', 'dx', 'dy' and 'rotate'
The
dx
dy
, and
rotate
on the
text
and
tspan
elements
are useful in
high-end typography scenarios where individual glyphs require
exact placement. These attributes are useful for minor positioning
adjustments between characters or for major positioning
adjustments, such as moving a section of text to a new location to
achieve the visual effect of a new line of text (compatible with
SVG 1.1). Note that the
dx
dy
, and
rotate
attributes are
ignored for auto-wrapped text (except for the initial
current text position
when the
content area
is specified by
the
inline-size
property).
It was decided at the 2015 Sydney F2F that 'dx', 'dy', and 'rotate'
would be ignored for auto-wrapped text. (Technically, it is not
difficult to apply them but it was not seen as being really useful.)
In situations where micro-level positioning adjustment are
necessary for advanced typographic control, the SVG content
designer needs to ensure that the necessary font will be available
for all viewers of the document (e.g., package up the necessary
font data in the form of an SVG font or an alternative WebFont
format which is stored at the same Web site as the SVG content)
and that the viewing software will process the font in the
expected way (the capabilities, characteristics and font layout
mechanisms vary greatly from system to system). If the SVG content
contains
dx
, or
dy
attribute values which are meant to correspond to a
particular font processed by a particular set of viewing software
and either of these requirements is not met, then the text might
display with poor quality.
The following additional rules apply to attributes
dx
dy
, and
rotate
when they
contain a list of numbers:
When a single character maps to a single glyph – In this
case, the
-th value for the
dx
dy
and
rotate
attributes is applied to the glyph that
corresponds to the
-th
character.
When a single character maps to multiple glyphs (e.g., when
an accent glyph is placed on top of a base glyph) – In this
case, the
-th value for
the
dx
, and
dy
values
are applied (i.e., the
current text position
is adjusted)
before rendering the first glyph. The rotation transformation
corresponding to the
-th
rotate
value is applied to the glyphs and to the inter-glyph advance
values corresponding to this character on a group basis (i.e.,
the rotation value creates a temporary new rotated coordinate
system, and the glyphs corresponding to the character are
rendered into this rotated coordinate system).
When multiple characters map to a single glyph (e.g., when a
ligature is used) – Suppose that the
-th and
+1)-th characters
map to a single glyph. In this case, the
-th value for the
dx
dy
and
rotate
attributes all apply when rendering the
glyph. The (
+1)-th values,
however, for
, and
rotate
are
ignored (exception: the final
rotate
value in the list
would still apply to subsequent characters), whereas
the
dx
and
dy
are applied to the subsequent
character (i.e., the
+2)-th character), if one
exists, by translating the
current text position
by the
given amounts before rendering the first glyph associated with
that character.
When there is a many-to-many mapping of characters to
glyphs (e.g., when three characters map to two glyphs, such as
when the first glyph expresses the first character and half
of the second character, and the second glyph expresses the
other half of the second character plus the third character)
– Suppose that the
-th,
+1)-th and
+2)-th characters map
to two glyphs. In this case, the
-th value for the
dx
, and
dy
values
are applied (i.e., the
current text position
is
adjusted) before rendering the first glyph. The rotation
transformation corresponding to the
-th
rotate
value is applied to both the two glyphs and the glyph advance
values for the first glyph on a group basis (i.e., the rotation
value creates a temporary new rotated coordinate system, and the
two glyphs are rendered into the temporary rotated coordinate
system). The (
+1)-th and
+2)-th values, however, for
the
, and
rotate
attributes are
not applied (exception: the final
rotate
value in the
list would still apply to subsequent characters), whereas
the (
+1)-th
and (
+2)-th values for
the
dx
and
dy
attributes are applied to the
subsequent character (i.e.,
the (
+3)-th character), if
one exists, by translating the
current text position
by
the given amounts before rendering the first glyph associated
with that character.
Relationship to bidirectionality –
Text is laid out in a two-step process, where any bidirectional
text is first re-ordered into a left-to-right string, and then
text layout occurs with the re-ordered text string. Whenever the
character data within a
tspan
element is re-ordered,
the corresponding elements within the
dx
dy
, and
rotate
are also
re-ordered to maintain the correspondence. For example,
suppose that there is the following
tspan
element:
Latin and Hebrew
and that the word "Hebrew" will be drawn right-to-left. First,
the character data and the corresponding values in
the
dx
list will be reordered, such that the text
string will be "Latin and werbeH" and the list of values for
the
dx
attribute will be "11 12 13 14 15 0 21 22 23 0
36 35 34 33 32 31". After this re-ordering, the glyphs
corresponding to the characters will be positioned using
standard left-to-right layout rules.
Example tspan04
uses the
rotate
attribute on the
tspan
element to rotate the
glyphs to be rendered. This example shows a single text string in a
tspan
element that contains more characters than the
number of values specified in the
rotate
attribute. In
this case the last value specified in the
rotate
attribute of the
tspan
must be applied to the remaining
characters in the string.



Example tspan04 - The number of rotate values is less than the number of
characters in the string.



Hello, out there



fill="none" stroke="blue" stroke-width="2" />

Example tspan04
View this example as SVG (SVG-enabled browsers only)
Example tspan05
specifies the
rotate
attribute on the
text
element and on all
but one of the child
tspan
elements to rotate the glyphs
to be rendered. The example demonstrates the propagation of the
rotate
attribute.



Example tspan05 - propagation of rotation values to nested tspan elements.

rotate="5,15,25,35,45,55">
Not

all characters

in

the

text

have a

specified

rotation

stroke="blue" stroke-width="2" />

Example tspan05
View this example as SVG (SVG-enabled browsers only)
Rotation of red text inside the
text
element:
The
rotate
value will rotate the characters in the text
"Not "
by 5, 15, 25 and 35 degrees respectively.
rotate
value is applied to the space that follows the
text
"Not"
, to the space in between the text in the
"child1" and "child5"
tspan
elements, and to the space
before the text
"rotation"
The next current
rotate
value specified is 45 followed
by 55. The current
rotate
value in the
text
element is incremented as subsequent characters in the text of the
child
tspan
elements are processed.
The next immediate
tspan
element specifies rotate values
for the text, hence the current
rotate
value will change to
the next value in the list (but is not used) as each character is
processed until the last value of 55 degrees is reached.
The last
rotate
value of 55 degrees will be applied to all
the characters in the text
"rotation"
Rotation of the orange text inside the "child1"
tspan
element:
The
rotate
value will rotate the first 4 characters in the
text
"all characters "
by -10, -20, -30 and -40
respectively.
The last
rotate
value of -40 becomes the current
rotate
value and will be applied to all subsequent
characters in the
tspan
element and to any child
tspan
elements that do not specify
rotate
values.
The "child4"
tspan
element does not specify any
rotate
values and thus uses the current
rotate
of
its ancestor ("child1"
tspan
element). All the characters
in the text
"text"
specified within the "child4"
tspan
element will be rotated by -40 degrees.
The last
rotate
value of -40 degrees will be applied to all
the characters in the text
"have a"
rotate
value is applied to the space in between the text
in the "child2" and "child4"
tspan
elements, and to the
space before the text
"have a"
Rotation of the yellow text inside the "child2"
tspan
element:
The
rotate
value will rotate the characters in the (yellow)
text
"in "
by 70, 60, and 50 degrees respectively.
rotate
value is applied to the space that follows the
text
"in"
There are more
rotate
values specified than characters,
thus the additional
rotate
values will be applied to the
"child3"
tspan
element which does not specified any
rotate
values.
The characters in the text
"the"
specified within the
"child3"
tspan
element will be rotated 40, 30 and 20
degrees respectively.
Rotation of the blue text inside the "child5"
tspan
element:
The
rotate
value will rotate all the characters in text
"specified"
by -10 degrees.
Only one
rotate
value is specified and is thus
applied to all characters in the
tspan
element.
The following diagram illustrates how the rotation values propagate to
tspan
elements nested withing a
text
element:
11.3. Text layout – Introduction
SVG 2 Requirement:
Include text layout improvements from SVG Tiny 1.2.
Resolution:
SVG 2 will include the improved text from SVG Tiny 1.2 on characters and glyphs, text layout, text selection, text search.
Purpose:
To include clearer descriptions of text layout; no functional change.
Owner:
Chris (
ACTION-3236
SVG 2 Requirement:
Support text in shapes.
Resolution:
SVG 2 will require automatic text wrapping compatible with CSS.
Purpose:
Text in flow charts, etc.
Owner:
Tav (no action)
This section gives a short overview of SVG text layout. It is
followed by sections that cover different aspects of text layout
in more detail.
Text layout in SVG is a multi-stage process that takes as input
text
element subtree and its property values and
produces a sequence of glyphs to render and their positions in
each
text content element
's coordinate system.
First, a
text
element and its descendants are laid out
inside a
content area
or
wrapping area
according to
CSS, as if the
text
were a block element and any
tspan
textPath
, and
descendants were
inline elements. This layout takes into account all paragraph
level and font related CSS properties described in this chapter.
The
content area
may be explicitly declared by setting the
inline-size
property, or by setting
the
shape-inside
property that defines or references an
SVG
shape
. If a
content area
is not declared, it
defaults to a rectangle of infinite width and height.
Second, any positioning given by
dx
and
dy
attributes are applied to
the resulting glyph positions from the CSS layout process.

The rules for which transforms are allowed depend on if
the
content area
was explicitly declared or not. If not
explicitly declared, the rules define the layout of
pre-formatted
text. If declared, the rules define the
layout of
auto-wrapped
text.
Third, the effect of the
text-anchor
property is applied
if necessary.
Finally, layout of glyphs for any
textPath
elements is
performed, converting
pre-formatted
text
to
text-on-a-path
Examples of the different types of text layout:
Pre-formatted:
For short strings of text (e.g. labels) or where exact
placement of glyphs is required (e.g. hand-kerned titles).
An example of multi-line pre-formatted text.

Example of multi-line,
pre-formatted text.

Pre-formatted text where a
tspan
element has
been used to create multi-line text.
Wrapped text:
For long strings of text where automatic text wrapping is
required.
An example of auto-wrapped text.

Example of text auto-wrapped.

Auto-wrapped text. The
inline-size
property defines a rectangular content area of infinite height
(shown in light blue).
Text on path:
For text that follows a specified path.
An example of text on a path.

d="M 50,50 C 100,0 200,100 250,50"/>

Text on a path.

Text on a path. The
textPath
element references a
path
element (shown in light
blue).
SVG 2 introduces the ability to automatically wrap text inside a
rectangle or other shape by specifying a
content area
. The
design of SVG wrapped text is motivated by the desire that SVG
text wrapping be as compatible as possible with text wrapping in
CSS in order that renderers that support CSS text wrapping can
implement SVG text wrapping easily (but without requiring non-HTML
compatible SVG renderers to implement HTML). There are several
differences between SVG and CSS text wrapping. The most important
is that in SVG, a
content area
must be explicitly provided
as SVG does not have an automatic finite (or semi-finite)
content area
(provided in CSS by the box model). Another
difference is that SVG does not have the

and

elements which create line breaks. Instead, SVG relies
on the
pre
and
pre-line
values of
white-space
to provide line breaks. SVG wrapped text also
allows a content-creation tool to provide a natural fallback for
SVG 1.1 renderers that do not support wrapped text (by use of
and
attributes in the
text
and
tspan
elements, which are ignored by SVG 2 renderers for
auto-wrapped text).
SVG's text layout options are designed to cover most general use
cases. If more complex layout is required (bulleted lists, tables,
etc.), text can be rendered in another XML namespace such as XHTML
HTML
] embedded inline within a
foreignObject
element.
11.4. Text layout – Content Area
content area
is defined by specifying in
text
element an
inline-size
property,
or a
shape-inside
property that defines
or references an SVG
shape
. If no
content area
is
provided, the
content area
defaults to a rectangle of
infinite width and height (see the
pre-formatted text
section).
If both an
inline-size
property and a
shape-inside
property with value other than 'none' are
given, the
shape-inside
property is used.
Wrapped text is laid out in a
wrapping area
. The
wrapping area
is normally the same as the
content area
. When the
content area
is defined using
the
shape-inside
property, the
wrapping area
may be smaller due to the presence of a
shape-subtract
property and/or a
shape-padding
property. The
shape-subtract
property (along with the
shape-margin
property) defines a
wrapping
context
. The
wrapping area
is found by
insetting the
content area
by the
shape-padding
distance,
and then subtracting the
wrapping context
Once a
wrapping area
is defined, the text is laid out
inside the
wrapping area
according to the rules of CSS
(respecting any special rules given in this section).
Constructing equivalent wrapping areas in SVG and HTML. The text
inside the wrapping areas is rendered the same in both cases.
Defining a
wrapping area
in SVG.

The
text
element has both a
shape-inside
property and a
shape-subtract
property.
The
shape-inside
property references a circle that
defines a
content area
(dotted purple line). The
shape-subtract
property referencing two semicircles
defines a
wrapping context
(dotted green line) which when
subtracted from the
content area
results in
the
wrapping area
(light blue line).
Defining a
wrapping area
in HTML.

wrapper