Copyright © 2023 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
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.
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 08 March 2023 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 subscribe
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:
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, https://www.w3.org/Graphics/SVG/, 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 https://www.w3.org/TR/. 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:
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:
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.
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.
SVG leverages and integrates with other W3C specifications and standards efforts, as described in the following:
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.
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.
This section defines a standard set of processing modes for SVG documents. Each processing mode specifies whether certain high level SVG features are enabled.
The features that can be enabled or disabled depending on the processing mode are as follows:
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 are URLs references or network access requests made by markup, style properties, script or other Web platform features used in the document, except for:
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 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 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.
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 |
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 |
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 |
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 |
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 |
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:
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 <image> 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]
'href'
referencesWhen 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.
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.
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.
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 |
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].
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:
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:
<?xml version="1.0" standalone="no"?> <!DOCTYPE SomeParentXMLGrammar PUBLIC "-//SomeParent" "http://SomeParentXMLGrammar.dtd"> <ParentXML> <!-- Elements from ParentXML go here --> <!-- The following is not conforming --> <z:rect xmlns:z="http://www.w3.org/2000/svg" x="0" y="0" width="10" height="10" /> <!-- More elements from ParentXML go here --> </ParentXML>
Instead, for the SVG part to become a conforming SVG DOM subtree, the file could be modified as follows:
<?xml version="1.0" standalone="no"?> <!DOCTYPE SomeParentXMLGrammar PUBLIC "-//SomeParent" "http://SomeParentXMLGrammar.dtd"> <ParentXML> <!-- Elements from ParentXML go here --> <!-- The following is conforming --> <z:svg xmlns:z="http://www.w3.org/2000/svg" width="100px" height="100px"> <z:rect x="0" y="0" width="10" height="10"/> </z:svg> <!-- More elements from ParentXML go here --> </ParentXML>
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.
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:
A conforming SVG markup fragment is also a conforming XML-compatible SVG markup fragment if it:
<?xml-stylesheet?>
processing instruction conforms to
Associating stylesheets with XML documents
[xml-stylesheet].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.
A document is a conforming SVG stand-alone file if:
There are various scenarios where an SVG document fragment is technically in error:
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:
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.
For software, the requirements for conformance depend on the category of program:
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.
A conforming SVG generator is a SVG generator that:
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.
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.
A 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 efficent 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.
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.
A 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].
A 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.
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.
A 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:
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:
image/svg+xml
,
it must be a well-formed, complete SVG document in order to be processed.
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.
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.
$$ (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) \left[ \begin{matrix} x_{\rm viewport} \\ y_{\rm viewport} \\ 1 \end{matrix} \right] = {\large \rm CTM} \cdot (single) \left[ \begin{matrix} x_{\rm userspace} \\ y_{\rm userspace} \\ 1 \end{matrix} \right] $$
A conforming SVG viewer that supports processing modes that include interaction must support the following additional features:
A conforming SVG viewer that supports processing modes that include script execution must support the following additional features:
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’).
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.
In order for a conforming SVG viewer to be considered a conforming high-quality SVG viewer, it must support the following additional features:
A conforming high-quality SVG viewer that supports processing modes that include script execution, declarative animation, or interaction must support the following additional features:
A conforming high-quality SVG viewer that supports processing modes that include interaction must support the following additional features:
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.
Implementations of SVG must implement the rendering model as described in this chapter, as modified in the appendix on conformance requirementswhich 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).
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.
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.
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
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.
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).
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.
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: ‘a’, ‘circle’, ‘ellipse’, ‘foreignObject’, ‘g’, ‘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.
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:
none
for the display property
Non-rendered elements:
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.
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 ‘a’ 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.
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 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.
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 layed 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.
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.
A new stacking context must be established at an SVG element for its descendants if:
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:
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.
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.
Grouping elements, such as the ‘g’ 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:
To provide for high quality rendering, filter primitives and other bitmap effects must be applied in the operating coordinate space.
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:
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’, ‘g’, ‘symbol’, ‘marker’, ‘a’, ‘switch’, ‘use’ and graphics elements.
The following example illustrates various usage of the opacity property on objects and groups.
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="175" viewBox="0 0 1200 350"> <!-- Background blue rectangle --> <rect x="100" y="100" width="1000" height="150" fill="blue"/> <!-- Red circles going from opaque to nearly transparent --> <circle cx="200" cy="100" r="50" fill="red" opacity="1"/> <circle cx="400" cy="100" r="50" fill="red" opacity=".8"/> <circle cx="600" cy="100" r="50" fill="red" opacity=".6"/> <circle cx="800" cy="100" r="50" fill="red" opacity=".4"/> <circle cx="1000" cy="100" r="50" fill="red" opacity=".2"/> <!-- Opaque group, opaque circles --> <g opacity="1"> <circle cx="182.5" cy="250" r="50" fill="red" opacity="1"/> <circle cx="217.5" cy="250" r="50" fill="green" opacity="1"/> </g> <!-- Group opacity: .5, opacity circles --> <g opacity=".5"> <circle cx="382.5" cy="250" r="50" fill="red" opacity="1"/> <circle cx="417.5" cy="250" r="50" fill="green" opacity="1"/> </g> <!-- Opaque group, semi-transparent green over red --> <g opacity="1"> <circle cx="582.5" cy="250" r="50" fill="red" opacity=".5"/> <circle cx="617.5" cy="250" r="50" fill="green" opacity=".5"/> </g> <!-- Opaque group, semi-transparent red over green --> <g opacity="1"> <circle cx="817.5" cy="250" r="50" fill="green" opacity=".5"/> <circle cx="782.5" cy="250" r="50" fill="red" opacity=".5"/> </g> <!-- Group opacity .5, semi-transparent green over red --> <g opacity=".5"> <circle cx="982.5" cy="250" r="50" fill="red" opacity=".5"/> <circle cx="1017.5" cy="250" r="50" fill="green" opacity=".5"/> </g> </svg>
In the example, the top row of circles have differing opacities, ranging from 1.0 to 0.2. The bottom row illustrates five ‘g’ elements, each of which contains overlapping red and green circles, as follows:
SVG supports three fundamental types of graphics elements that can be rendered onto the canvas:
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.
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.
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.
SVG supports the following clipping/masking features:
Both, clipping and masking, are specified in the module CSS Masking [css-masking-1].
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.
See the Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification [CSS2] for the definition of overflow.
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:
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.
In this specification, attributes are defined with an attribute definition table, which looks like this:
Name | Value | Initial value | Animatable |
---|---|---|---|
exampleattr | <length> | 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:
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:
The insertion of the <number> 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.
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.
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.
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) |
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 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
SVGElementNameElement
, 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.
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.
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:
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 0.
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:
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:
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.
The values will be SVGNumber, SVGLength, DOMPoint or SVGTransform objects, or DOMString values, depending on value's type.
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 doubles.
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.
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].
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 DocumentAndElementEventHandlers; 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.
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:
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:
This will include:
This method would have been more aptly named as getClientCTM
,
but the name getScreenCTM
is kept for historical reasons.
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 x or y 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 x or y 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:
As with getTotalLength, this does not take into account the ‘pathLength’ attribute.
The SVGNumber interface is used primarily to represent a <number> 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:
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:
The SVGLength interface is used to represent a value that can be a <length>, <percentage> or <number> 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:
An SVGLength object maintains an internal <length> or <percentage> or <number> 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 <number> interpreted as a value in px. |
SVG_LENGTHTYPE_PERCENTAGE | A <percentage>. |
SVG_LENGTHTYPE_EMS | A <length> with an em unit. |
SVG_LENGTHTYPE_EXS | A <length> with an ex unit. |
SVG_LENGTHTYPE_PX | A <length> with a px unit. |
SVG_LENGTHTYPE_CM | A <length> with a cm unit. |
SVG_LENGTHTYPE_MM | A <length> with a mm unit. |
SVG_LENGTHTYPE_IN | A <length> with an in unit. |
SVG_LENGTHTYPE_PT | A <length> with a pt unit. |
SVG_LENGTHTYPE_PC | A <length> 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:
For example, for a <length> 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:
On setting value, the following steps are run:
The valueInSpecifiedUnits IDL attribute represents the numeric factor of the SVGLength's value. On getting valueInSpecifiedUnits, the following steps are run:
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:
The valueAsString IDL attribute represents the SVGLength's value as a string. On getting valueAsString, the following steps are run:
On setting valueAsString, the following steps are run:
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:
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:
The SVGAngle interface is used to represent a value that can be an <angle> or <number> 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:
An SVGAngle object maintains an internal <angle> or <number> 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 <number> interpreted as a value in degrees. |
SVG_ANGLETYPE_DEG | An <angle> with a deg unit. |
SVG_ANGLETYPE_RAD | An <angle> with a rad unit. |
SVG_ANGLETYPE_GRAD | An <angle> 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:
For example, for an <angle> 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:
On setting value, the following steps are run:
The valueInSpecifiedUnits IDL attribute represents the numeric factor of the SVGAngle's value. On getting valueInSpecifiedUnits, the following steps are run:
On setting valueInSpecifiedUnits, the following steps are run:
The valueAsString IDL attribute represents the SVGAngle's value as a string. On getting valueAsString, the following steps are run:
On setting valueAsString, the following steps are run:
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:
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:
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 a few unanimated attributes that take a list of strings.
Most list interfaces take the following form:
interface SVGNameList { 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.
A 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).
A 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.
A list interface object is synchronized by running the following steps:
Whenever a list element object is to be detached, the following steps are run, depending on the list element type:
Whenever a list element object is to be attached, the following steps are run, depending on the list element type:
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:
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:
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:
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:
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:
The removeItem method is used to remove an item from the list. When removeItem(index) is called, the following steps are run:
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:
The behavior of the indexed property setter is the same as that for the replaceItem method.
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.
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.
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.
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
.
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:
On setting baseVal, the reflected attribute is set to "true" if the value is true, and "false" otherwise.
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:
On setting baseVal, the following steps are run:
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:
For example, the definition of ‘order’ says that the implicit second integer is the same as the explicit first integer.
On setting baseVal, the following steps are run:
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:
For example, the definition of ‘kernelUnitLength’ says that the implicit second number is the same as the explicit first number.
On setting baseVal, the following steps are run:
An SVGAnimatedLength object is used to reflect either (a) an animatable attribute that takes a <length>, <percentage> or <number> 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:
An SVGAnimatedAngle object is used to reflect the <angle> 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 <angle> value of the reflected ‘orient’ attribute. On getting baseVal or animVal, an SVGAngle object is returned that:
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 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:
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:
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.
An SVGAnimatedRect object is used to reflect an animatable attribute that takes a rectangle value as specified by an x, y, 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, a 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:
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.
An SVGAnimatedNumberList object is used to reflect an animatable attribute that takes a list of <number> 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.
An SVGAnimatedLengthList object is used to reflect an animatable attribute that takes a list of <length>, <percentage> or <number> 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.
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. |
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.
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.
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:
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.
An SVG document fragment consists of any number of SVG elements contained within an ‘svg’ element.
An SVG document fragment can range from an empty fragment (i.e., no content inside of the ‘svg’ element), to a very simple SVG document fragment containing a single SVG graphics element such as a ‘rect’, to a complex, deeply nested collection of container elements and graphics elements.
An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent HTML or XML document.
The following example shows simple SVG content embedded inline as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the ‘svg’ and ‘ellipse’ elements belong to the SVG namespace:
<?xml version="1.0" standalone="yes"?> <parent xmlns="http://example.org" xmlns:svg="http://www.w3.org/2000/svg"> <!-- parent contents here --> <svg:svg width="4cm" height="8cm"> <svg:ellipse cx="2cm" cy="4cm" rx="2cm" ry="1cm" /> </svg:svg> <!-- ... --> </parent>
This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="4cm" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Four separate rectangles </desc> <rect x="0.5cm" y="0.5cm" width="2cm" height="1cm"/> <rect x="0.5cm" y="2cm" width="1cm" height="1.5cm"/> <rect x="3cm" y="0.5cm" width="1.5cm" height="2cm"/> <rect x="3.5cm" y="3cm" width="1cm" height="0.5cm"/> <!-- Show outline of viewport using 'rect' element --> <rect x=".01cm" y=".01cm" width="4.98cm" height="3.98cm" fill="none" stroke="blue" stroke-width=".02cm" /> </svg>
‘svg’ elements can appear in the middle of SVG content. This is the mechanism by which SVG document fragments can be embedded within other SVG document fragments.
Another use for ‘svg’ elements within the middle of SVG content is to establish a new SVG viewport. (See Establishing a new SVG viewport.)
When SVG is parsed as a XML, for compliance with the Namespaces in XML Recommendation [xml-names], an SVG namespace declaration must be provided so that all SVG elements are identified as belonging to the SVG namespace.
When using the HTML syntax, the namespace is provided automatically by the HTML parser.
<html> <svg viewBox="0 0 100 100"> <circle cx="50" cy="50" r="50" fill="green"> </svg> </html>
As the example shows there's no need to have an ‘xmlns’ attribute declaring that the element is in the SVG namespace when using the HTML parser. The HTML parser will automatically create the SVG elements in the proper namespace.
This section should talk about how a document's behavior is defined in terms of the DOM, and also explain how the HTML parser can create SVG fragments.
The SVG 2 namespace is http://www.w3.org/2000/svg
,
which is the same as for earlier versions of SVG.
The following are possible ways to provide a namespace declaration when SVG is parsed as XML. An ‘xmlns’ attribute without a namespace prefix could be specified on an ‘svg’ element, which means that SVG is the default namespace for all elements within the scope of the element with the ‘xmlns’ attribute:
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"> <rect x="10" y="10" width="80" height="80" fill="green" /> </svg>
If a namespace prefix is specified on the ‘xmlns’
attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"
),
then the corresponding namespace is not the default namespace, so an
explicit namespace prefix must be assigned to the elements:
<svg:svg xmlns:svg="http://www.w3.org/2000/svg" viewBox="0 0 100 100"> <svg:rect x="10" y="10" width="80" height="80" fill="green" /> </svg:svg>
Namespace prefixes can be specified on ancestor elements (illustrated in the above example). For more information, refer to the Namespaces in XML Recommendation [xml-names].
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 |
The x and y attributes specify the top-left corner of the rectangular region into which an embedded ‘svg’ element is placed. On an outermost svg element, these attributes have no effect.
For outermost svg elements, the width and height attributes specify the intrinsic size of the SVG document fragment. For embedded ‘svg’ elements, they specify the size of the rectangular region into which the ‘svg’ element is placed. In either case, a computed style of auto is treated equivalent to 100%.
If an SVG document is likely to be referenced as a component of another document, the author will often want to include a ‘viewBox’ attribute on the outermost svg element of the referenced document. This attribute provides a convenient way to design SVG documents to scale-to-fit into an arbitrary SVG viewport.
The ‘svg’ element exposes as event handler content attributes a number of the event handlers of the Window object. It also mirrors their event handler IDL attributes.
The onblur, ‘onerror’, onfocus, ‘onload’, and ‘onscroll’ event handlers of the Window object, exposed on the ‘svg’ element, replace the generic event handlers with the same names normally supported by SVG elements.
The ‘g’ element is a container element for grouping together related graphics elements.
A group of elements, as well as individual objects, can be given a name using the ‘id’ attribute. Named groups are needed for several purposes such as animation and re-usable objects.
An example:
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="5cm" height="5cm"> <desc>Two groups, each of two rectangles</desc> <g id="group1" fill="red"> <rect x="1cm" y="1cm" width="1cm" height="1cm"/> <rect x="3cm" y="1cm" width="1cm" height="1cm"/> </g> <g id="group2" fill="blue"> <rect x="1cm" y="3cm" width="1cm" height="1cm"/> <rect x="3cm" y="3cm" width="1cm" height="1cm"/> </g> <!-- Show outline of viewport using 'rect' element --> <rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm" fill="none" stroke="blue" stroke-width=".02cm"/> </svg>
A ‘g’ element can contain other ‘g’ elements nested within it, to an arbitrary depth.
SVG allows a graphical object to be defined for later reuse. To do this, SVG makes extensive use of the URL reference construct [rfc3987]. For example, to fill a rectangle with a linear gradient, a ‘linearGradient’ element may be defined with an ‘id’ property that may be referenced in the value for the rectangle's fill property, as in the following:
<linearGradient id="MyGradient">...</linearGradient> <rect style="fill:url(#MyGradient)"/>
Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.
It is recommended that, where possible, referenced elements be defined prior to the elements that use them, in document order. Collecting all referenced elements inside of a single ‘defs’ element near the top of the file can make the markup easier to read and understand.
The ‘defs’ element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a ‘defs’.
The content model for ‘defs’ is the same as for the ‘g’ element; thus, any element that can be a child of a ‘g’ can also be a child of a ‘defs’, and vice versa.
Elements that are descendants of a ‘defs’ are not rendered directly; the display value for the ‘defs’ element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute. Note, however, that the descendants of a ‘defs’ are always present in the source tree and thus can always be referenced by other elements; thus, the value of the display property on the ‘defs’ element does not prevent those elements from being referenced by other elements.
The ‘symbol’ element is used to define graphical templates which can be instantiated by a ‘use’ element but which are not rendered directly.
A ‘symbol’ establishes a nested coordinate system for the graphics it contains. When a symbol is instantiated as the referenced element of a ‘use’ element, it is therefore rendered very similarly to a nested ‘svg’ element.
The x, y, width, and height geometry properties have the same effect as on an ‘svg’ element, when the ‘symbol’ is instantiated by a ‘use’ element. In particular, if width and height compute to auto (and are not over-ridden by values on the instantiating ‘use’ element), then they will be treated as a value of 100%.
New in SVG 2. Allowing geometry properties to be specified on a symbol provides a more consistent rendering model, and allows authors to set a default size for each symbol (which may still be over-ridden by attributes on the ‘use’ element).
Name | Value | Initial value | Animatable |
---|---|---|---|
refX | <length> | left | center | right | (none) | yes |
refY | <length> | top | center | bottom | (none) | yes |
New in SVG 2. Added to make it easier to align symbols to a particular point, as is often done in maps. Similar to the matching attributes on ‘marker’.
Add refX/refY to symbol element. Resolved at Leipzig F2F. Status: Done.
We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'. Status: Done.
The ‘refX’ and ‘refY’ attributes define the reference point of the symbol which is to be placed exactly at the symbol's x,y positioning coordinate, as defined by the cumulative effect of the x and y properties and any transformations on the ‘symbol’ and its host ‘use’ element.
Keyword values have the same meaning as for the ‘refX’ and ‘refY’ attributes on the ‘marker’ element, resolving to 0%, 50%, or 100% in the applicable direction.
Unlike other positioning attributes, ‘refX’ and ‘refY’ are interpreted as being in the coordinate system of the symbol contents, after application of the ‘viewBox’ and ‘preserveAspectRatio’ attributes. If one or both of the attributes is not specified, no adjustment is made in the corresponding dimension, and the top or left side of the symbol's rectangular viewport region (regardless of the ‘viewBox’ coordinates) is positioned at the x,y point.
For backwards compatibility, the behavior when ‘refX’ and ‘refY’ are not specified on a ‘symbol’ is different from when they are specified with a value of 0, and therefore different from the behavior when equivalent attributes are not specified on a ‘marker’.
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.
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 |
The ‘use’ element references another element, a copy of which is rendered in place of the ‘use’ in the document. The referenced element may be a container element, in which case a copy of the complete SVG document subtree rooted at that element is used.
The cloned content inherits styles from the ‘use’ element and can be the target of user events. However, these cloned element instances remain linked to the referenced source and reflect DOM mutations in the original. In addition, all style rules that apply in the scope of the referenced element also apply in the scope of the cloned shadow tree.
The x, y, width and height geometric properties specify the positioning of the referenced element. The width and height attributes only have an effect if the referenced element defines a viewport (i.e., if it is a ‘svg’ or ‘symbol’); if so, a value other than auto for the ‘use’ element overrides the value of the corresponding geometric property on that element.
A negative value for width or height is invalid and must be ignored. If width or height is zero, and the properties have an effect on the referenced element, then rendering of that element will be disabled.
The x and y properties affect the user coordinate system for the element. See the Layout section for implementation details.
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | yes |
An URL reference to the element/fragment within an SVG document to be cloned for rendering.
The ‘use’ element can reference an entire SVG document by specifying an ‘href’ value without a fragment. Such references are taken to be referring to the root element of the referenced document.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.New in SVG 2. An ‘href’ without a fragment allows an entire SVG document to be referenced without having to ensure that it has an ID on its root element.
User agents may restrict external resource documents for security reasons. In particular, this specification does not allow cross-origin resource requests in ‘use’. A future version of this or another specification may provide a method of securely enabling cross-origin re-use of assets.
When the ‘href’ attribute is set (or, in the absence of an ‘href’ attribute, an ‘xlink:href’ attribute), the user agent must process the URL. The target element that results from URL processing is the referenced element of the ‘use’.
If the referenced element that results from resolving the URL is not an SVG element, then the reference is invalid and the ‘use’ element is in error.
If the referenced element is a (shadow-including) ancestor of the ‘use’ element, then this is an invalid circular reference and the ‘use’ element is in error.
Otherwise, the user agent must generate a shadow tree of re-used graphics to render as the contents of the ‘use’ element, as described in the next section, The use-element shadow tree.
A ‘use’ that has an unresolved or invalid URL reference is not rendered. For the purpose of bounding box calculations, it is equivalent to an empty container element.
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:
When the user agent successfully resolves a ‘use’ element to identify a referenced element, the user agent must create a use-element shadow tree whose host is the ‘use’ element itself. The shadow tree must be created even if the ‘use’ element is not rendered because it is a descendent of a never-rendered element, because of conditional processing, or because of the display property being set to none on it or an ancestor element.
Each node in the shadow tree is an instance of a corresponding node from the referenced document subtree. The shadow nodes all descend from the instance root, which is the instance of the referenced element, and which itself is a direct child of the shadow root node.
The shadow tree is open (inspectable by script), but read-only.
Any attempt to directly modify the elements, attributes, and other nodes in the shadow tree
must throw a NoModificationAllowedError
.
Within a use-element shadow tree, ‘script’ elements are inert (do not execute).
Previous versions of SVG restricted the contents of the shadow tree to SVG graphics elements. This specification allows any valid SVG document subtree to be cloned. Cloning non-graphical content, however, will not usually have any visible effect.
If the referenced element is in an external file, then all URL references in attributes and style properties must be made absolute as described in Generating the absolute URL, before copying the value to the element instances. The shadow tree itself uses the same document base URL as the document that includes it.
The user agent must ensure that all mutations to the referenced document subtree are reflected in the shadow tree. This includes changes to elements, attributes, and text and other nodes. In addition, changes to the stylesheets in effect for the referenced graphics must be reflected in changes to the stylesheets in the shadow tree's scope, as described futher in the section on style inheritance.
If either the ‘use’ element or the referenced element is altered in a way that causes the ‘use’ element's URL reference to become unresolved again, then the entire shadow tree for that use element is discarded.
When a ‘use’ references another element which is another ‘use’ or whose content contains a ‘use’ element, then the shadow DOM cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an invalid circular reference. The ‘use’ element or element instance whose shadow tree would create the circular reference is in error and must not be rendered by the user agent.
The value of the x, y, width and height properties on a ‘use’ element are used to position the re-used graphics and to set the viewport size if the referenced element defines a nested viewport. The effect of these properties on a ‘use’ element is notably different from their effect on a graphics element, or from their effect in CSS box layout.
The x and y properties define an additional transformation (translate(x,y), where x and y represent the computed value of the corresponding property) to be applied to the ‘use’ element, after any transformations specified with other properties (i.e., appended to the right-side of the transformation list).
For historical reasons, the supplemental transformation is applied to the ‘use’ element itself, rather than solely to the re-used content in the shadow tree. This affects the coordinate system used for any masks, clipping paths, or filters applied to the ‘use’ element and calculated in userSpaceOnUse units.
To apply userSpaceOnUse graphical effects in an un-transformed coordinate space, while also using the x and y to position the graphics, authors can nest the ‘use’ element inside a ‘g’, and apply the graphical effects to the ‘g’ element.
The width and height properties on the ‘use’ element override the values for the corresponding properties on a referenced ‘svg’ or ‘symbol’ element when determining the used value for that property on the instance root element. However, if the computed value for the property on the ‘use’ element is auto, then the property is computed as normal for the element instance.
These properties can therefore be used to scale a graphic that defines its own coordinate system, each time it is re-used. Because auto is the initial value, if dimensions are not explicitly set on the ‘use’ element, the values set on the ‘svg’ or ‘symbol’ will be used as defaults.
The width and height properties on the ‘use’ element have no effect if the referenced element does not establish a new viewport. In particular, the ‘use’ element does not itself establish a new viewport, and therefore does not affect the interpretation of percentages in the re-used graphics.
In all other ways, rendering and layout of elements within the use-element shadow tree occurs as if the ‘use’ element was a container for its shadow content. In particular, unless elements within the shadow tree establish a new viewport, they must be drawn in the coordinate system in which the ‘use’ element is defined (including any cumulative transformations). This affects the interpretation of percentage lengths, and also graphical effects with userSpaceOnUse units.
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:
special
.In the SVG 1.1 style-cloning model, the specified style values would be cloned from the original element to the element instance. The re-used circle would have the same styles as the original, except that the fill value would be inherited from the ‘use’ (orange) instead of from the ‘g’ (blue).
In the shadow DOM model required by SVG 2, the styles for the re-used circle are calculated as follows:
special
; instead, stroke color on the circle is inherited from the host ‘use’ element (purple).The re-used circle therefore differs from the original in both fill color (because it inherits from a different element) and stroke color (because the complex selector no longer matches).
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="200" height="100" viewBox="0 0 200 100"> <title>Style inheritance and the use element</title> <desc> Two circles, one of which is a re-styled clone of the other. This file demonstrates one of the cases where the shadow-DOM style matching rules in SVG 2 have a different effect than the SVG 1.1 style cloning rules. The original circle on the left should have blue fill and green stroke. In a conforming SVG 1.1 user agent, the re-used circle on the right should have orange fill and green stroke. In a conforming SVG 2 user agent, the re-used circle should have orange fill and purple stroke. In all cases, the stroke should be partially transparent and 20 units wide, relative to a total circle diameter of 100 units. </desc> <style type="text/css"> circle { stroke-opacity: 0.7; } .special circle { stroke: green; } use { stroke: purple; fill: orange; } </style> <g class="special" style="fill: blue"> <circle id="c" cy="50" cx="50" r="40" stroke-width="20" /> </g> <use xlink:href="#c" x="100" /> </svg>
Previous versions of SVG
were not clear about how dynamic pseudo-classes
(such as :hover
)
should apply to element instances.
The shadow tree model requires that all such pseudo-classes
are matched independently to the
element instance or to its corresponding element,
depending on which element the user is interacting with.
Specifying 'visibility:hidden' on a ‘use’ element does not guarantee that the referenced content will not be rendered. Unlike the display or the opacity properties, the visibility property does not appy directly to container elements, and therefore does not apply directly to the ‘use’ element. Because visibility is normally inherited, hiding the use element will often hide the child content, but not necessarily. If any graphics elements in the shadow tree have 'visibility:visible' specified, then that element will be visible even if the ‘use’ element specifies 'visibility:hidden'.
In the following example, key style rules are as follows:
.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.
The example also demonstrates inheritance of other style properties (fill and stroke) specified on the ‘use’ elements, and how these are also not used if any elements within the symbol specify explicit values (e.g., the pink noses and ears and the white tails).
The Web Animations API [web-animations-1] and the SVG Animations specification [svg-animation] define non-CSS ways to animate attributes and styles on targetted elements without directly manipulating DOM properties (see the Animation appendix for details). User agents that implement those features must ensure that all animations that apply to an element in a referenced document subtree also apply to instances of that element in a use-element shadow tree, as described in this section.
Scripted animations created by directly manipulating attributes on elements in the referenced graphics (including the ‘style’ attribute or its IDL property) will be propagated to the element instances in the shadow tree in the same manner as any other DOM manipulations.
Animation effects applied using CSS will be duplicated along with other stylesheet rules, following the procedure specified in the Style Scoping and Inheritance section.
All animations within a use-element shadow tree operate in the same document timeline as for the corresponding use element, regardless of whether the referenced element is from the same or an external document.
For animation effects applied using a Web Animations API method [web-animations-1], if the target of the animation is a corresponding element to an element instance in a shadow tree, the user agent must construct a ShadowAnimation whose source is that Animation object and whose target is the element instance. If there are multiple instances of the element in different trees, then there will be multiple shadow animations, one for each.
The user agent must create such a ShadowAnimation for all Web Animations API animations in effect (including pending and frozen animations) at the time the shadow tree is generated, and for any new animations applied while the shadow tree exists. The user agent must not create ShadowAnimation objects for CSS animations or animation elements (as these are duplicated separately).
As part of the interface definition, a ShadowAnimation is read-only, and must reflect any changes to its sourceAnimation.
Any attempts to directly apply new animations
to a target that is a read-only element instance (or pseudo-element)
within a use-element shadow tree
must throw a NoModificationAllowedError
.
For each animation element [svg-animation] that targets an element in the referenced document subtree, the user agent must ensure that an equivalent animation element is in effect in the use-element shadow tree. If the animation element itself is part of the referenced document subtree, then this happens as a matter of course through the creation of an element instance for the animation element. Otherwise, the user agent must generate an element instance for the animation element that has the same effect as if it was a node in the shadow tree. The effective document order for these generated animation elements must be the same as the document order for their corresponding elements.
Each animation element or instance must only affect a target element in the same node tree (shadow or light), regardless of whether the targetting is implicit (the parent element) or explicit (a URL cross-reference to an element ‘id’). In this way, the one-to-one relationship between animation elements and target elements is preserved.
The ‘id’ attribute is cloned, like any other attribute, from the corresponding element to the element instance; This does not conflict with the requirement for ‘id’ to be unique, because the clone and the original are in distinct node trees.
All animation elements, in the document or in the shadow trees, which are timed to begin or end in response to an event on another element identified by its ‘id’ attribute, must also begin or end when any instance of an element with that ‘id’ receives the same event. This is consistent with how event listeners on a referenced element also listen to events on instances of that element, as described in the section on Event handling in use-element shadow trees. This behavior does not apply to animation begin or end times defined only by an event and not by an ‘id’ (and therefore implicitly listening for the event on the target element); in that case, each animation element is only triggered by its own target.
At the time an instance of an animation element is generated within a shadow tree, if there is an active animation associated with the corresponding element (including a frozen animation), and the timing event that initiated that animation would also have initiated the instance if it existed, then the animation for the element instance must be initiated, with its begin time adjusted backwards in the document timeline to match the timing of the corresponding element.
In many cases, the requirements of this section mean that the element instance and its corresponding element will animate synchronously. This will be the case if the animation is purely time-based, or if it begins and ends in response to user interaction on an element referenced by its ‘id’. However, if the animation is triggered by a user interaction event on the targetted element (implicitly), then only the element or element instance that receives the interaction event will display the animation.
This is a change from previous versions of SVG, which required all animations on the corresponding element to be mirrored, regardless of user interaction, but which did not offer clear guidance for responding to user interactions with the element instances. The change ensures that interactive animations declared with animation elements behave in the same manner as interactive CSS styles and CSS animations.
In order to create animations that apply to all instances when any instance or the original element receives an event, specify the element ‘id’ explicitly:
<set href="#target" begin="mouseover" ... />
<!-- only affects the element that is moused over -->
<set href="#target" begin="target.mouseover" ... />
<!-- affects all instances of the element with the id 'target',
in all light and shadow node trees,
when any of them are moused over -->
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.
SVG contains a ‘switch’ element along with attributes ‘requiredExtensions’ and ‘systemLanguage’ to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.
Attributes ‘requiredExtensions’ and ‘systemLanguage’ act as tests and evaluate to either true or false. The ‘switch’ renders the first of its children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.
When an element is excluded because of conditional processing,
it is treated as if it had a used value of none
for the display property.
Similar to the display property, conditional processing
attributes only affect the direct rendering of elements and do
not prevent elements from being successfully referenced by
other elements (such as via a ‘use’).
In consequence:
Previous versions of SVG included a third conditional processing attribute,
requiredFeatures
.
This was intended to allow authors to provide fallback behavior for user agents
that only implemented parts of the SVG specification.
Unfortunately, poor specification and implementation of this attribute made it unreliable
as a test of feature support.
The ‘switch’ element evaluates the ‘requiredExtensions’ and ‘systemLanguage’ attributes on its direct child elements in order, and then processes and renders the first child for which these attributes evaluate to true. All others will be bypassed and therefore not rendered. If the child element is a container element such as a ‘g’, then the entire subtree is either processed/rendered or bypassed/not rendered.
In SVG, when evaluating the ‘systemLanguage’ attribute, the order of evaluation of descendant elements of the ‘switch’ element must be as if the 'allowReorder' attribute, defined in the SMIL specification [SMIL] always has a value of 'yes'.
Note that the values of properties display and visibility have no effect on ‘switch’ element processing. In particular, setting display to none on a child of a ‘switch’ element has no effect on true/false testing associated with ‘switch’ element processing.
The ‘switch’ element does not affect the processing of ‘script’ and ‘style’ elements.
For more information and an example, see Embedding foreign object types.
The ‘requiredExtensions’ attribute defines a list of required language extensions. Language extensions are capabilities within a user agent that go beyond the feature set defined in this specification. Each extension is identified by an URL reference.
Name | Value | Initial value | Animatable |
---|---|---|---|
requiredExtensions | set of space-separated tokens [HTML] | (none) | no |
The value is a list of URL references which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.
If a given URL reference contains white space within itself, that white space must be escaped.
If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute ‘requiredExtensions’, the attribute evaluates to "false".
‘requiredExtensions’ is often used in conjunction with the ‘switch’ element. If the ‘requiredExtensions’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.
The URL names for the extension should include versioning information, such as "http://example.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.
Name | Value | Initial value | Animatable |
---|---|---|---|
systemLanguage | set of comma-separated tokens [HTML] | (none) | no |
The value is a set of comma-separated tokens, each of which must be a Language-Tag value, as defined in BCP 47 [BCP47].
Evaluates to "true" if one of the language tags indicated by user preferences is a case-insensitive match of one of the language tags given in the value of this parameter, or if one of the language tags indicated by user preferences is a case-insensitive prefix of one of the language tags given in the value of this parameter such that the first tag character following the prefix is "-".
Evaluates to "false" otherwise.
If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute ‘systemLanguage’, the attribute evaluates to "false".
Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.
The prefix rule simply allows the use of prefix tags if this is the case.
Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.
Multiple languages may be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:
<text systemLanguage="mi, en"><!-- content goes here --></text>
However, just because multiple languages are present within the object on which the ‘systemLanguage’ test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the ‘systemLanguage’ test attribute should only include "en".
Authoring note: Authors should realize that if several alternative language objects are enclosed in a ‘switch’, and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a ‘switch’ which is acceptable in all cases.
‘systemLanguage’ is often used in conjunction with the ‘switch’ element. If the ‘systemLanguage’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.
Multilingual descriptive text selection, based on the ‘lang’ attribute, was added to allow internationalization of the ‘desc’ and ‘title’ elements.
New in SVG 2. Adding 'lang' resolved at Rigi Kaltbad face-to-face. Removed text that limited number of 'desc' and 'title' elements. Status: Done.
Any container element or graphics element in an SVG document can have zero or more ‘desc’ and/or ‘title’ elements as children, whose content is text. ‘desc’ and ‘title’ elements are not visually rendered as part of the graphics. The display value for the ‘title’ and ‘desc’ elements must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.
Multiple sibling ‘desc’ or ‘title’ elements must have
different languages,
as defined using a ‘lang’ attribute (or xml:lang
attribute) on the descriptive element or an ancestor.
The user agent must select the element of each type whose language best
matches language preferences set by the user.
A descriptive element with an empty-string language tag
(indicating no language, for example a text alternative consisting of emoji symbols)
is a lowest-priority match for any user, ranked below all user-specified language preferences.
If multiple equally valid matches exist, the first match should be used.
If no match exists for either 'title' or 'desc', the first element of that type must be selected.
The following example shows alternative language titles on a re-used star icon,
inline in an HTML document.
The example assumes that the HTML document as a whole has a correctly-declared language of en
(English without a specified country code).
<svg> <use href="#star"> <title>Favourite</title> <title lang="en-us">Favorite</title> <title lang="nl">Favoriet</title> <title lang="">★</title> </use> </svg>
The first title
element inherits the language of the document (en
); the others have explicitly-declared languages for each element.
If the user's preferred language (out of those provided) is American English, the icon title is the American spelling "Favorite".
If the user's preferred language is Dutch, the icon title is "Favoriet".
If the user's preference list includes generic English ranked higher than Dutch, the title is "Favourite" with British spelling.
If the user does not understand either Dutch or English, the title will be the star symbol character—which is not ideal (most screen readers will read it as a localized version of "black star"), but better than no text alternative at all.
Authors should be aware that SVG 1.1-supporting user agents
that have not yet implemented multi-lingual descriptive text
will normally select the first element of each type, regardless of user preferences.
SVG 1.1 user agents may also fail to recognize a title
element that is not the first child of its parent,
or a desc
element that has previous siblings that are not other descriptive elements.
The use of more than one ‘title’ or ‘desc’ element to provide localised information is at risk, with no known implementations.
User agents must make the text content of selected 'title' and 'desc' elements available to platform accessibility APIs as part of the name and description computation for the parent element, as defined in the SVG Accessibility API Mappings [SVG-AAM] specification.
Inclusion of any 'title' or 'desc' elements as a direct child of a rendered element indicates that the rendered element is of semantic importance in the graphic. Authors should not, and SVG generators must not, include empty 'title' or 'desc' elements with no text content or whitespace-only text content, as this will result in a nameless object being presented to assistive technology users.
If an individual graphic element has no meaning on its own, alternative text should instead be provided for the nearest container element that describes a meaningful object. Authors should use grouping (‘g’) elements to structure their drawing elements into meaningful objects, and name those groups with ‘title’. Conversely, if a container object is used simply to apply styles or layout, and neither defines an object nor provides meaningful grouping structure, it does not need alternative text.
Descriptive text elements whose parent is not rendered may be used by authors or authoring tools as reference information; authors are warned that this data is not normally available to end users viewing the graphic through assistive technologies. Nonetheless, a non-rendered element may be referenced as part of the accessible name or description of a rendered element (as defined in SVG-AAM), and the recursive computation will use descriptive child elements of the referenced element.
Description and title elements may contain marked-up text from other namespaces, using standard XML mechanisms to indicate the namespace. However, authors should not rely on such markup to provide meaning to alternative text; only the plain text content is currently required to be exposed to assistive technologies.
The HTML parser treats all markup within ‘title’ and ‘desc’ the same way it treats markkup in an HTML fragment; most elements will be assigned to the HTML namespace.
User agents may use markup within ‘title’ to influence the visual presentation of titles (such as tooltips), but are not required to do so.
The ‘title’ child element represents a short text alternative for the element.
On a link, this could be the title or a description of the target resource; on an image or drawing object, it could be a short description of the graphic; on interactive content, it could be a label for, or instructions for, use of the element; and so forth.
Authors should not provide redundant information in a ‘title’ element if there is also a visible label for the drawing element (e.g., using a ‘text’ element). Instead, the visual label should be associated with the drawing element using an ‘aria-labelledby’ attribute.
Interactive user agents should make the plain text content of ‘title’ elements available in response to user interaction, in a manner consistent with platform conventions; existing user agents commonly render ‘title’ elements as a tooltip on hovering the parent element.
Authors should provide a ‘title’ child element to the root svg element within a stand-alone SVG document. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesn't provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, user agents should always make the content of the ‘title’ child element to the root svg element available to users. However, this is typically done through other means than the tooltips used for nested SVG and graphics elements, e.g., by displaying in a browser tab.
The ‘desc’ element represents more detailed textual information for the element such as a description. This is typically exposed to assistive technologies to provide more detailed information, such as a description of the visual appearance of a graphic or help to explain the functionality of a complex widget. It is not typically available to other users, so should not be used for essential instructions.
Authors may associate detailed information, including visible text, with part of the graphic using ‘aria-describedby’ attribute (on the described element or a parent container), with the value being an ID reference to one or more SVG or HTML elements containing the description. The ‘aria-describedby’ attribute takes precedence over the child ‘desc’ when providing a description. If an element has both visible description and a child ‘desc’ element providing supplementary information, authors should explicitly include the ‘id’ of the element itself in its own ‘aria-describedby’ list, in order to concatenate the two descriptions together.
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 content is not directly rendered; the display value for the ‘metadata’ element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.
Here is an example of how metadata can be included in an SVG document. The example uses the Dublin Core version 1.1 schema. (Other XML-compatible metadata languages, including ones not based on RDF, can be used also.)
<?xml version="1.0" standalone="yes"?> <svg width="4in" height="3in" xmlns = 'http://www.w3.org/2000/svg'> <desc xmlns:myfoo="http://example.org/myfoo"> <myfoo:title>This is a financial report</myfoo:title> <myfoo:descr>The global description uses markup from the <myfoo:emph>myfoo</myfoo:emph> namespace.</myfoo:descr> <myfoo:scene><myfoo:what>widget $growth</myfoo:what> <myfoo:contains>$three $graph-bar</myfoo:contains> <myfoo:when>1998 $through 2000</myfoo:when> </myfoo:scene> </desc> <metadata> <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#" xmlns:dc = "http://purl.org/dc/elements/1.1/" > <rdf:Description about="http://example.org/myfoo" dc:title="MyFoo Financial Report" dc:description="$three $bar $thousands $dollars $from 1998 $through 2000" dc:publisher="Example Organization" dc:date="2000-04-11" dc:format="image/svg+xml" dc:language="en" > <dc:creator> <rdf:Bag> <rdf:li>Irving Bird</rdf:li> <rdf:li>Mary Lambert</rdf:li> </rdf:Bag> </dc:creator> </rdf:Description> </rdf:RDF> </metadata> </svg>
For user agents that support HTML, the following HTML elements (in the HTML namespace) must be supported in SVG documents:
Note that the base
element will affect all URL values in the document, including e.g. paint server references or ‘use’ element references.
However, when processing URL references
to identify a specific target element,
the user agent must always compare the generated absolute URL against the current document base URL
to determine whether it is a same-document URL reference.
In this way, target-fragment only references to elements in the same document remain valid,
regardless of any changes to the document base URL.
SVG allows inclusion of elements from foreign namespaces anywhere within the SVG content. In general, the SVG user agent must include the unknown foreign-namespaced elements in the DOM but will ignore and exclude them for rendering purposes.
The notable exceptions is described in the Embedded Content chapter under Embedding Foreign Object Types.
Additionally, SVG allows inclusion of attributes from foreign namespaces on any SVG element. The SVG user agent must include unknown attributes in the DOM but should otherwise ignore unknown attributes.
Authors should be aware that unknown namespaced elements and attributes will not be parsed as such by the HTML parser. Instead, the namespace prefix will be included in the tag or attribute name, elements will be placed in the parent element namespace and attributes in the default namespace.
To add custom attributes in a way that will result in consistent parsing in both XML and HTML documents, authors may use the ‘data-*’ attributes. These can be added to SVG ‘metadata’ elements if the information they encode is not associated with any other element in the document.
SVG's ability to include foreign namespaces can be used for the following purposes:
For example, a business graphics authoring application might want to include some private data within an SVG document so that it could properly reassemble the chart (a pie chart in this case) upon reading it back in:
<?xml version="1.0" standalone="yes"?> <svg width="4in" height="3in" xmlns = 'http://www.w3.org/2000/svg'> <defs> <myapp:piechart xmlns:myapp="http://example.org/myapp" title="Sales by Region"> <myapp:pieslice label="Northern Region" value="1.23"/> <myapp:pieslice label="Eastern Region" value="2.53"/> <myapp:pieslice label="Southern Region" value="3.89"/> <myapp:pieslice label="Western Region" value="2.04"/> <!-- Other private data goes here --> </myapp:piechart> </defs> <desc>This chart includes private data in another namespace </desc> <!-- In here would be the actual SVG graphics elements which draw the pie chart --> </svg>
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.
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].
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.
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.
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.
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.
Note that the above list of ARIA attributes may be expanded by future WAI-ARIA specifications.
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]).
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]
The following table defines the default implicit ARIA semantics that apply to SVG elements. Each language feature (element) in a cell in the first column implies the ARIA semantics (role, states, and/or properties) given in the cell in the second column of the same row. The third column defines restrictions as to what WAI-ARIA semantic (role, state, or property) may or may not apply.
For many graphics elements, an implicit role is only assigned if the author provides information that indicates semantic importance. The complete inclusion criteria for the accessibility tree are defined by the SVG Accessibility API Mappings specification for user agents [svg-aam-1.0]. For authors, the preferred means of indicating semantic importance is to provide an accessible name for the element. This can be done through a direct child ‘title’ element, or through the ‘aria-label’ or ‘aria-labelledby’ attributes. Authors should use one of these methods to provide an accessible name for any content that is essential to the comprehension of the SVG, and especially for any interactive content.
Language feature | Default implied ARIA semantics | Allowed roles |
---|---|---|
‘a’ | link role
if the element has a valid href or xlink:href attribute.
For a elements that are not links, the default semantics are the same as
tspan if the a element is a descendent of text ,
or the same as g otherwise. |
no restrictions |
‘circle’ | graphics-symbol role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘clipPath’ | none | no role may be applied |
‘defs’ | none | no role may be applied |
‘desc’ | none | no role may be applied |
‘ellipse’ | graphics-symbol role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘feBlend’ | none | no role may be applied |
‘feColorMatrix’ | none | no role may be applied |
‘feComponentTransfer’ | none | no role may be applied |
‘feComposite’ | none | no role may be applied |
‘feConvolveMatrix’ | none | no role may be applied |
‘feDiffuseLighting’ | none | no role may be applied |
‘feDisplacementMap’ | none | no role may be applied |
‘feDistantLight’ | none | no role may be applied |
‘feDropShadow’ | none | no role may be applied |
‘feFlood’ | none | no role may be applied |
‘feFuncA’ | none | no role may be applied |
‘feFuncB’ | none | no role may be applied |
‘feFuncG’ | none | no role may be applied |
‘feFuncR’ | none | no role may be applied |
‘feGaussianBlur’ | none | no role may be applied |
‘feImage’ | none | no role may be applied |
‘feMerge’ | none | no role may be applied |
‘feMergeNode’ | none | no role may be applied |
‘feMorphology’ | none | no role may be applied |
‘feOffset’ | none | no role may be applied |
‘fePointLight’ | none | no role may be applied |
‘feSpecularLighting’ | none | no role may be applied |
‘feSpotLight’ | none | no role may be applied |
‘feTile’ | none | no role may be applied |
‘feTurbulence’ | none | no role may be applied |
‘filter’ | none | no role may be applied |
‘foreignObject’ | group role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘g’ | group role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘image’ | img role |
no restrictions |
‘line’ | graphics-symbol role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘linearGradient’ | none | no role may be applied |
‘marker’ | none | no role may be applied |
‘mask’ | none | no role may be applied |
‘metadata’ | none | no role may be applied |
‘mpath’ | none | no role may be applied |
‘path’ | graphics-symbol role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘pattern’ | none | no role may be applied |
‘polygon’ | graphics-symbol role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘polyline’ | graphics-symbol role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘radialGradient’ | none | no role may be applied |
‘rect’ | graphics-symbol role
if the element meets the inclusion criteria,
otherwise none |
no restrictions |
‘script’ | none | no role may be applied |
‘stop’ | none | no role may be applied |
‘style’ | none | no role may be applied |
‘svg’ | graphics-document role |
no restrictions |
‘switch’ | none | no role may be applied |
‘symbol’ | graphics-object role
if the element is a rendered element instance
that meets the inclusion criteria,
otherwise none |
no restrictions |
‘text’ | 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 |
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.
An SVGSVGElement object represents an ‘svg’ element in the DOM. The SVGSVGElement interface also contains miscellaneous utility methods, such as data type object factory methods.
An SVGSVGElement object maintains an internal DOMPoint object, called its current translate point object, which is the object returned from the currentTranslate IDL attribute.
[Exposed=Window] interface SVGSVGElement : SVGGraphicsElement { [SameObject] readonly attribute SVGAnimatedLength x; [SameObject] readonly attribute SVGAnimatedLength y; [SameObject] readonly attribute SVGAnimatedLength width; [SameObject] readonly attribute SVGAnimatedLength height; attribute float currentScale; [SameObject] readonly attribute DOMPointReadOnly currentTranslate; NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement); NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement); boolean checkIntersection(SVGElement element, DOMRectReadOnly rect); boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect); undefined deselectAll(); SVGNumber createSVGNumber(); SVGLength createSVGLength(); SVGAngle createSVGAngle(); DOMPoint createSVGPoint(); DOMMatrix createSVGMatrix(); DOMRect createSVGRect(); SVGTransform createSVGTransform(); SVGTransform createSVGTransformFromMatrix(optional DOMMatrix2DInit matrix = {}); Element getElementById(DOMString elementId); // Deprecated methods that have no effect when called, // but which are kept for compatibility reasons. unsigned long suspendRedraw(unsigned long maxWaitMilliseconds); undefined unsuspendRedraw(unsigned long suspendHandleID); undefined unsuspendRedrawAll(); undefined forceRedraw(); }; SVGSVGElement includes SVGFitToViewBox; SVGSVGElement includes WindowEventHandlers;
The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.
The currentScale and currentTranslate IDL attributes represent an additional transform applied to the SVG. They only have an effect on the outermost svg element of an SVG document fragment.
The document's magnification and panning
transform is a 2x3 matrix of the form
[currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]
.
The value of the ‘transform’ property does not affect
currentScale or
currentTranslate.
Previous versions of SVG recommended that user agents implement controls, by default,
for the user to set the scale (zoom) and translate (pan) of the graphic.
Transformations from these user actions would be reflected
in the values of currentScale
and currentTranslate
.
These user controls were not well implemented, and are no longer recommended.
However, authors should be aware that the user agent may update these values.
The obsolete attribute zoomAndPan="disable"
, on the outermost SVG element,
should disable any user agent manipulation of the values based on user action,
but may have unwanted side effects in some user agents.
The interaction of currentScale and currentTranslate with other ways of transforming the document root (transforms and SVG views) is poorly defined. See the GitHub issue for more.
On getting currentScale, the following steps are run:
On setting currentScale, the following steps are run:
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:
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:
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.
To find the non-container graphics elements within a given element element, the following steps are run:
When getIntersectionList(rect, referenceElement) or getEnclosureList(rect, referenceElement) is called, the following steps are run:
When checkIntersection(element, rect) or checkEnclosure(element, rect) is called, the following steps are run:
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 <number> 0. |
createSVGAngle | A new, detached SVGAngle object whose value is the unitless <number> 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.
An SVGGElement object represents a ‘g’ element in the DOM.
[Exposed=Window] interface SVGGElement : SVGGraphicsElement { };
An SVGDefsElement object represents a ‘defs’ element in the DOM.
[Exposed=Window] interface SVGDefsElement : SVGGraphicsElement { };
An SVGDescElement object represents a ‘desc’ element in the DOM.
[Exposed=Window] interface SVGDescElement : SVGElement { };
An SVGMetadataElement object represents a ‘metadata’ element in the DOM.
[Exposed=Window] interface SVGMetadataElement : SVGElement { };
An SVGTitleElement object represents a ‘title’ element in the DOM.
[Exposed=Window] interface SVGTitleElement : SVGElement { };
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.
An SVGUseElement object represents a ‘use’ element in the DOM.
[Exposed=Window] interface SVGUseElement : SVGGraphicsElement { [SameObject] readonly attribute SVGAnimatedLength x; [SameObject] readonly attribute SVGAnimatedLength y; [SameObject] readonly attribute SVGAnimatedLength width; [SameObject] readonly attribute SVGAnimatedLength height; [SameObject] readonly attribute SVGElement? instanceRoot; [SameObject] readonly attribute SVGElement? animatedInstanceRoot; }; SVGUseElement includes SVGURIReference;
The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.
The instanceRoot and
animatedInstanceRoot
IDL attributes both point to the instance root,
the SVGElementInstance that is a direct child
of this element's shadow root
(u.instanceRoot
is equivalent to getting u.shadowRoot.firstChild
).
If this element does not have a shadow tree
(for example, because its URI is invalid
or because it has been disabled by conditional processing),
then getting these attributes returns null.
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 { };
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.
The ShadowAnimation inteface defines a read-only Animation object, which mirrors all changes to the sourceAnimation object from which it was constructed. They are used to mirror author-initiated animation objects in the use-element shadow tree.
[Exposed=Window] interface ShadowAnimation : Animation { constructor(Animation source, (Element or CSSPseudoElement) newTarget); [SameObject] readonly attribute Animation sourceAnimation; };
The sourceAnimation IDL property points to the Animation object passed in the constructor.
The constructor generates a new ShadowAnimation object,
which reflects all properties on the sourceAnimation,
except that its effect
is created by constructing a new
KeyframeEffectReadOnly
using the keyframe effect of the sourceAnimation as its source,
and then modifying its target
to match the newTarget
parameter.
A ShadowAnimation is read-only.
Any attempt to set any of the inherited IDL properties,
or call any of the Animation methods that change its state,
must throw a NoModificationAllowedError
.
However, the user agent must ensure that
any changes to the properties or state
of the sourceAnimation are reflected
in changes to the ShadowAnimation.
An SVGSwitchElement object represents a ‘switch’ element in the DOM.
[Exposed=Window] interface SVGSwitchElement : SVGGraphicsElement { };
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.
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.
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.
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.
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:
<svg xmlns="http://www.w3.org/2000/svg"> <style> @import url(mystyles.css); </style> <rect .../> </svg>
would behave similarly to:
<svg xmlns="http://www.w3.org/2000/svg"> <link xmlns="http://www.w3.org/1999/xhtml" rel="stylesheet" href="mystyles.css" type="text/css"/> <rect .../> </svg>
Or, in XML documents, external CSS style sheets may be included using the <?xml-stylesheet?> processing instruction [xml-stylesheet].
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.
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.
<!-- English messages --> <text class="info" lang="en">Variable declared twice</text> <text class="warning" lang="en">Undeclared variable</text> <text class="error" lang="en">Bad syntax for variable name</text> <!-- French messages --> <text class="info" lang="fr">Variable déclarée deux fois</text> <text class="warning" lang="fr">Variable indéfinie</text> <text class="error" lang="fr">Erreur de syntaxe pour variable</text>
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:
<text style="fill: green;" lang="en">Variable declared twice</text> <text style="fill: yellow;" lang="en">Undeclared variable</text> <text style="fill: red;" lang="en">Bad syntax for variable name</text>
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.
Note that ‘cx’, ‘cy’, ‘r’, ‘x’, ‘y’, ‘width’ and ‘height’ attributes are not always presentation attributes. For example, the ‘x’ attribute on ‘text’ and ‘tspan’ is not a presentation attribute for the x property, and the ‘r’ attribute on a ‘radialGradient’ is not a presentation attribute for the r 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.
The following properties must be supported by all SVG user agents:
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] { text-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].
Besides the features described above, the following CSS features must be also supported in SVG user agents:
An SVGStyleElement object represents a ‘style’ element in the DOM.
[Exposed=Window] interface SVGStyleElement : SVGElement { attribute DOMString type; attribute DOMString media; attribute DOMString title; }; SVGStyleElement includes LinkStyle;
The type, media and title IDL attributes reflect the ‘type’, ‘media’ and ‘title’ content attributes, respectively.
Beside SVG's styling properties, SVG also defines geometry properties. Geometry properties describe the position and dimension of the graphics elements ‘circle’, ‘ellipse’, ‘rect’, ‘image’, ‘foreignObject’ and the ‘svg’ element.
Name: | cx |
---|---|
Value: | <length-percentage> |
Initial: | 0 |
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.
Name: | cy |
---|---|
Value: | <length-percentage> |
Initial: | 0 |
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.
Name: | r |
---|---|
Value: | <length-percentage> |
Initial: | 0 |
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 r property describes the radius of the ‘circle’ element.
A negative value for r is invalid and must be ignored.
Name: | rx |
---|---|
Value: | <length-percentage> | 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.
Name: | ry |
---|---|
Value: | <length-percentage> | 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.
Name: | x |
---|---|
Value: | <length-percentage> |
Initial: | 0 |
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 x property describes the horizontal coordinate of the position of the element.
Name: | y |
---|---|
Value: | <length-percentage> |
Initial: | 0 |
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 y property describes the vertical coordinate of the position of the element.
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.
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.
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.
The transform applied to content contained by the element is given by translate(translate-x, translate-y) scale(scale-x, scale-y).
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:
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:
<?xml version="1.0" standalone="yes"?> <parent xmlns="http://some.url"> <!-- SVG graphic --> <svg xmlns='http://www.w3.org/2000/svg' width="100px" height="200px"> <path d="M100,100 Q200,400,300,100"/> <!-- rest of SVG graphic would go here --> </svg> </parent>
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".
<?xml version="1.0" standalone="no"?> <svg width="300px" height="100px" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example InitialCoords - SVG's initial coordinate system</desc> <g fill="none" stroke="black" stroke-width="3" > <line x1="0" y1="1.5" x2="300" y2="1.5" /> <line x1="1.5" y1="0" x2="1.5" y2="100" /> </g> <g fill="red" stroke="none" > <rect x="0" y="0" width="3" height="3" /> <rect x="297" y="0" width="3" height="3" /> <rect x="0" y="97" width="3" height="3" /> </g> <g font-size="14" font-family="Verdana" > <text x="10" y="20">(0,0)</text> <text x="240" y="20">(300,0)</text> <text x="10" y="90">(0,100)</text> </g> </svg>
User agents must support the transform property and presentation attribute as defined in [css-transforms-1].
Name | Value | Initial value | Animatable |
---|---|---|---|
viewBox | [<min-x>,? <min-y>,? <width>,? <height>] | As if not specified. | yes |
<min-x>, <min-y>, <width>, <height> = <number>
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 <min-x>, <min-y>, <width> and <height>, 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 <width> or <height> 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.
<?xml version="1.0" standalone="no"?> <svg width="300px" height="200px" viewBox="0 0 1500 1000" preserveAspectRatio="none" xmlns="http://www.w3.org/2000/svg"> <desc>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.</desc> <!-- This rectangle goes from (0,0) to (1500,1000) in user coordinate system. Because of the viewBox attribute above, the rectangle will end up filling the entire area reserved for the SVG content. --> <rect x="0" y="0" width="1500" height="1000" fill="yellow" stroke="blue" stroke-width="12" /> <!-- A large, red triangle --> <path fill="red" d="M 750,100 L 250,900 L 1250,900 z"/> <!-- A text string that spans most of the SVG viewport --> <text x="100" y="600" font-size="200" font-family="Verdana" > Stretch to fit </text> </svg>
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:
<?xml version="1.0" standalone="no"?> <svg width="300px" height="200px" xmlns="http://www.w3.org/2000/svg"> <g transform="scale(0.2)"> <!-- Rest of document goes here --> </g> </svg>
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:
<?xml version="1.0" standalone="no"?> <svg width="150px" height="200px" xmlns="http://www.w3.org/2000/svg"> <g transform="scale(0.1 0.2)"> <!-- Rest of document goes here --> </g> </svg>
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 <min-x> or <min-y>.
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.
Name | Value | Initial value | Animatable |
---|---|---|---|
preserveAspectRatio | <align> <meetOrSlice>? | xMidYMid meet | yes |
<align> = none | xMinYMin | xMidYMin | xMaxYMin | xMinYMid | xMidYMid | xMaxYMid | xMinYMax | xMidYMax | xMaxYMax
<meetOrSlice> = 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 <align> 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 <align> parameter must be one of the following strings:
The <meetOrSlice> parameter is optional and, if provided, is separated from the <align> value by one or more spaces and then must be one of the following strings:
meet (the default) - Scale the graphic such that:
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:
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).
<svg width="450px" height="300px" xmlns="http://www.w3.org/2000/svg"> <desc>Example PreserveAspectRatio - illustrates preserveAspectRatio attribute</desc> <style type="text/css"> text { font-size: 9; } rect { fill: none; stroke: blue; } </style> <defs> <g id="smile"> <rect x='.5' y='.5' width='29' height='39' style="fill:black;stroke:red"/> <circle cx='15' cy='20' r='10' fill='yellow'/> <circle cx='12' cy='17' r='1.5' fill='black'/> <circle cx='17' cy='17' r='1.5' fill='black'/> <path d='M 10 24 A 8 8 0 0 0 20 24' stroke='black' stroke-width='2'/> </g> </defs> <rect x="1" y="1" width="448" height="298"/> <text x="10" y="30">SVG to fit</text> <g transform="translate(20,40)"><use href="#smile" /></g> <text x="10" y="110">Viewport 1</text> <g transform="translate(10,120)"><rect x='.5' y='.5' width='49' height='29'/></g> <text x="10" y="180">Viewport 2</text> <g transform="translate(20,190)"><rect x='.5' y='.5' width='29' height='59'/></g> <g id="meet-group-1" transform="translate(100, 60)"> <text x="0" y="-30">--------------- meet ---------------</text> <g> <text y="-10">xMin*</text> <rect x='.5' y='.5' width='49' height='29'/> <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" width="50" height="30"> <use href="#smile" /> </svg> </g> <g transform="translate(70,0)"> <text y="-10">xMid*</text> <rect x='.5' y='.5' width='49' height='29'/> <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" width="50" height="30"> <use href="#smile" /> </svg> </g> <g transform="translate(0,70)"> <text y="-10">xMax*</text> <rect x='.5' y='.5' width='49' height='29'/> <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" width="50" height="30"> <use href="#smile" /> </svg> </g> </g> <g id="meet-group-2" transform="translate(250, 60)"> <text x="0" y="-30">---------- meet ----------</text> <g> <text y="-10">*YMin</text> <rect x='.5' y='.5' width='29' height='59'/> <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" width="30" height="60"> <use href="#smile" /> </svg> </g> <g transform="translate(50, 0)"> <text y="-10">*YMid</text> <rect x='.5' y='.5' width='29' height='59'/> <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" width="30" height="60"> <use href="#smile" /> </svg> </g> <g transform="translate(100, 0)"> <text y="-10">*YMax</text> <rect x='.5' y='.5' width='29' height='59'/> <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" width="30" height="60"> <use href="#smile" /> </svg> </g> </g> <g id="slice-group-1" transform="translate(100, 220)"> <text x="0" y="-30">---------- slice ----------</text> <g> <text y="-10">xMin*</text> <rect x='.5' y='.5' width='29' height='59'/> <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" width="30" height="60"> <use href="#smile" /> </svg> </g> <g transform="translate(50,0)"> <text y="-10">xMid*</text> <rect x='.5' y='.5' width='29' height='59'/> <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" width="30" height="60"> <use href="#smile" /> </svg> </g> <g transform="translate(100,0)"> <text y="-10">xMax*</text> <rect x='.5' y='.5' width='29' height='59'/> <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" width="30" height="60"> <use href="#smile" /> </svg> </g> </g> <g id="slice-group-2" transform="translate(250, 220)"> <text x="0" y="-30">--------------- slice ---------------</text> <g> <text y="-10">*YMin</text> <rect x='.5' y='.5' width='49' height='29'/> <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" width="50" height="30"> <use href="#smile" /> </svg> </g> <g transform="translate(70,0)"> <text y="-10">*YMid</text> <rect x='.5' y='.5' width='49' height='29'/> <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" width="50" height="30"> <use href="#smile" /> </svg> </g> <g transform="translate(140,0)"> <text y="-10">*YMax</text> <rect x='.5' y='.5' width='49' height='29'/> <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" width="50" height="30"> <use href="#smile" /> </svg> </g> </g> </svg>
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:
<?xml version="1.0" standalone="no"?> <svg width="4in" height="3in" xmlns="http://www.w3.org/2000/svg"> <desc>This SVG drawing embeds another one, thus establishing a new SVG viewport </desc> <!-- The following statement establishing a new SVG viewport and renders SVG drawing B into that SVG viewport --> <svg x="25%" y="25%" width="50%" height="50%"> <!-- drawing B goes here --> </svg> </svg>
For an extensive example of creating new SVG viewports, see Example PreserveAspectRatio.
The following elements establish new SVG viewports:
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.
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 <percentage> values that are defined to be relative to the size of SVG viewport:
sqrt((width)**2 + (height)**2)/sqrt(2)
.Example Units below illustrates some of the processing rules for different types of units.
<?xml version="1.0" standalone="no"?> <svg width="400px" height="200px" viewBox="0 0 4000 2000" xmlns="http://www.w3.org/2000/svg"> <title>Example Units</title> <desc>Illustrates various units options</desc> <!-- Frame the picture --> <rect x="5" y="5" width="3990" height="1990" fill="none" stroke="blue" stroke-width="10"/> <g fill="blue" stroke="red" font-family="Verdana" font-size="150"> <!-- Absolute unit specifiers --> <g transform="translate(400,0)"> <text x="-50" y="300" fill="black" stroke="none">Abs. units:</text> <rect x="0" y="400" width="4in" height="2in" stroke-width=".4in"/> <rect x="0" y="750" width="384" height="192" stroke-width="38.4"/> <g transform="scale(2)"> <rect x="0" y="600" width="4in" height="2in" stroke-width=".4in"/> </g> </g> <!-- Relative unit specifiers --> <g transform="translate(1600,0)"> <text x="-50" y="300" fill="black" stroke="none">Rel. units:</text> <rect x="0" y="400" width="2.5em" height="1.25em" stroke-width=".25em"/> <rect x="0" y="750" width="375" height="187.5" stroke-width="37.5"/> <g transform="scale(2)"> <rect x="0" y="600" width="2.5em" height="1.25em" stroke-width=".25em"/> </g> </g> <!-- Percentages --> <g transform="translate(2800,0)"> <text x="-50" y="300" fill="black" stroke="none">Percentages:</text> <rect x="0" y="400" width="10%" height="10%" stroke-width="1%"/> <rect x="0" y="750" width="400" height="200" stroke-width="31.62"/> <g transform="scale(2)"> <rect x="0" y="600" width="10%" height="10%" stroke-width="1%"/> </g> </g> </g> </svg>
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 ‘g’ 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.
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:
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.
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.
<svg xmlns="http://www.w3.org/2000/svg"> <title>Bounding Box Calculation</title> <desc>Examples of elements with different bounding box results based on context.</desc> <defs id="defs-1"> <rect id="rect-1" x="20" y="20" width="40" height="40" fill="blue" /> </defs> <g id="group-1"> <use id="use-1" href="#rect-1" x="10" y="10" /> <g id="group-2" display="none"> <rect id="rect-2" x="10" y="10" width="100" height="100" fill="red" /> </g> </g> </svg>
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 d 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 <use href="#bad" x="10" y="10"/>
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:
The algorithm to compute the bounding box is as follows, depending on the type of element:
The values of the fill, fill-opacity and fill-rule properties do not affect fill-shape.
The values of the stroke-opacity, stroke-dasharray and stroke-dashoffset do not affect the calculation of the stroke shape.
The fill, stroke and markers input arguments to this algorithm do not affect the bounding box returned for these elements.
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 othwerise; markers is true if we are computing the decorated bounding box, and false otherwise; and clipped is false.
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 (‘r’) 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 (‘x’, ‘y’, ‘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 (‘x’, ‘y’, ‘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 (‘x’, ‘y’, ‘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 are 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.
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.
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:
<svg xmlns="http://www.w3.org/2000/svg" width="10cm" height="5cm"> ... </svg>
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.
<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="50%" viewBox="0 0 200 200"> ... </svg>
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.
<svg xmlns="http://www.w3.org/2000/svg" width="10cm" viewBox="0 0 200 200"> ... </svg>
In this case the intrinsic aspect ratio is 1:1.
<svg xmlns="http://www.w3.org/2000/svg" width="75%" height="10cm" viewBox="0 0 200 200"> ... </svg>
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.
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 |
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.
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.
<circle vector-effect="veValue" transform="translate(xo yo)" cx="xf" cy="yf" r=".."/>
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, xf and yf are user coordinate of the corresponding element and its descendant. And, xo and yo are matrix element e and f 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.
veValue | Formula |
---|---|
non-scaling-size |
|
non-rotation |
|
non-scaling-size non-rotation |
|
fixed-position |
|
fixed-position non-scaling-size |
|
fixed-position non-rotation |
|
fixed-position non-scaling-size non-rotation |
|
Below is normal coordinate transformation formula for nested viewport coordinate systems without vector effects. xviewport(UA) and yviewport(UA) are coordinates which under the immediate control of user agent. CTMthis is CTM for the transformation matrix from user coordinate system of an target graphic to viewport coordinate system to which it belongs. CTMparent is CTM for the transformation matrix from aforementioned viewport coordinate system to viewport coordinate system of the parent of that. And, CTMroot is CTM for rootmost viewport coordinate system (UA).
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.
When screen value is specified, user agent computes coordinates combining either of seven formulas of the preceding chapter, and the following formulas.
Below is an example of the non-scaling-stroke vector-effect.
<?xml version="1.0"?> <svg xmlns="http://www.w3.org/2000/svg" width="6cm" height="4cm" viewBox="0 0 600 400" viewport-fill="rgb(255,150,200)"> <desc>Example non-scaling stroke</desc> <rect x="1" y="1" width="598" height="398" fill="none" stroke="black"/> <g transform="scale(9,1)"> <line stroke="black" stroke-width="5" x1="10" y1="50" x2="10" y2="350"/> <line vector-effect="non-scaling-stroke" stroke="black" stroke-width="5" x1="32" y1="50" x2="32" y2="350"/> <line vector-effect="none" stroke="black" stroke-width="5" x1="55" y1="50" x2="55" y2="350"/> </g> </svg>
Below is an example of the none vector-effect (no vector effect).
Before changing CTM | After changing CTM |
Source code
<svg xmlns="http://www.w3.org/2000/svg" viewBox="-50,-50,500,500" height="500" width="500"> <rect x="-50" y="-50" width="500" height="500" stroke="orange" stroke-width="3" fill="none"/> <!-- Nested user coordinate system is transformed by this transform attribute --> <g transform="matrix(2.1169438081370817,0.3576047954311102,-0.3576047954311102,1.4700998667618626,0,0) translate(-50,-50)"> <svg viewBox="-50,-50,500,500" height="500" width="500"> <!-- Graph paper on the this svg's base user coordinate system --> <g stroke="green" stroke-width="1" fill="none"> <circle cx="0" cy="0" r="10"/> <circle cx="150" cy="150" r="7"/> <path fill="green" stroke="none" d="M0,-3 L30,-3 25,-10 50,0 25,10 30,3 0,3z"/> <line x1="-100" y1="-100" x2="600" y2="-100" stroke-dasharray="5,5"/> <line x1="-100" y1="000" x2="600" y2="000"/> <line x1="-100" y1="100" x2="600" y2="100" stroke-dasharray="5,5"/> <line x1="-100" y1="200" x2="600" y2="200" stroke-dasharray="5,5"/> <line x1="-100" y1="300" x2="600" y2="300" stroke-dasharray="5,5"/> <line x1="-100" y1="400" x2="600" y2="400" stroke-dasharray="5,5"/> <line x1="-100" y1="500" x2="600" y2="500" stroke-dasharray="5,5"/> <line y1="-100" x1="-100" y2="600" x2="-100" stroke-dasharray="5,5"/> <line y1="-100" x1="000" y2="600" x2="000"/> <line y1="-100" x1="100" y2="600" x2="100" stroke-dasharray="5,5"/> <line y1="-100" x1="200" y2="600" x2="200" stroke-dasharray="5,5"/> <line y1="-100" x1="300" y2="600" x2="300" stroke-dasharray="5,5"/> <line y1="-100" x1="400" y2="600" x2="400" stroke-dasharray="5,5"/> <line y1="-100" x1="500" y2="600" x2="500" stroke-dasharray="5,5"/> </g> <!-- Figure having vector effect --> <!-- A thick red right arrow and small rectangle on this figure's nested user coordinate system origin --> <path id="ve" vector-effect="none" 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"/> </svg> </g> </svg>
Below is an example of the non-scaling-size.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="non-scaling-size" 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 |
<path id="ve" vector-effect="non-rotation" 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 |
<path id="ve" vector-effect="non-scaling-size non-rotation" 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 |
<path id="ve" vector-effect="fixed-position" 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 |
<path id="ve" vector-effect="non-scaling-size fixed-position" 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 |
<path id="ve" vector-effect="non-rotation fixed-position" 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 |
<path id="ve" vector-effect="non-scaling-size non-rotation fixed-position" 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"/>
The SVGTransform interface is used to represent <transform-function> 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:
An SVGTransform object maintains an internal <transform-function> 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 | A matrix(…) value. |
SVG_TRANSFORM_TRANSLATE | A translate(…) value. |
SVG_TRANSFORM_SCALE | A scale(…) value. |
SVG_TRANSFORM_ROTATE | A rotate(…) value. |
SVG_TRANSFORM_SKEWX | A skewX(…) value. |
SVG_TRANSFORM_SKEWY | A 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:
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:
The setMatrix method is used to set the SVGTransform to a given matrix value. When setMatrix(matrix) is called, the following steps are run:
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.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:
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:
A 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, a 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:
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 <transform-list> 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:
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:
The behavior of all other interface members of SVGLengthList are defined in List interfaces.
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.
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:
On setting align, the following steps are run:
The meetOrSlice IDL attribute represents the alignment keyword part of the ‘preserveAspectRatio’ value. On getting, the following steps are run:
On setting meetOrSlice, the following steps are run:
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 reflcting IDL attribute of type SVGAnimatedPreserveAspectRatio was obtained from.
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, a segment-completing close path operation is defined, which cannot currently be represented in the basic path syntax.
The outline of a shape for a ‘path’ element is specified using the d property. See Path data below.
A path is defined by including a ‘path’ element on which the d 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 M indicates a moveto, the Ls indicate linetos, and the z indicates a closepath).
<?xml version="1.0" standalone="no"?> <svg width="4cm" height="4cm" viewBox="0 0 400 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <title>Example triangle01- simple example of a 'path'</title> <desc>A path that draws a triangle</desc> <rect x="1" y="1" width="398" height="398" fill="none" stroke="blue" /> <path d="M 100 100 L 300 100 L 200 300 z" fill="red" stroke="blue" stroke-width="3" /> </svg>
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:
M 100 100 L 200 200
M100 100L200 200
M 100 200 L 200 100 L -100 -200
M 100 200 L 200 100 -100 -200
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:
In the description of the path commands, cpx and cpy represent the coordinates of the current point.
Name: | d |
---|---|
Value: | none | <string> |
Initial: | none |
Applies to: | ‘path’ |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animation type: | See prose |
The d 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 <string> value specifies a shape using a path data string. The contents of the <string> 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 d 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 canbe used in path data strings. Those that draw straight line segments include the lineto commands (L, l, H, h, V and v) and the close path commands (Z and z). These three groups of commands draw curves:
The "moveto" commands (M or m) 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 |
---|---|---|---|
M (absolute) m (relative) |
moveto | (x y)+ | Start a new sub-path at the given (x,y) coordinates. M (uppercase) indicates that absolute coordinates will follow; m (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 (m) 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 m command is used, the position moved to is (cpx + x, cpy + y).
The "closepath" (Z or z) 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 |
---|---|---|---|
Z or z |
closepath | (none) | Close the current subpath by connecting it back to the current subpath's initial point (see prose above). Since the Z and z commands take no parameters, they have an identical effect. |
A closed subpath must be closed with a "closepath" command, this "joins" the first and last path segments. Any other path is an open subpath.
A 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.
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.
A segment-completing close path operation combines with the previous path command, with two effects:
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.
The various "lineto" commands draw straight lines from the current point to a new point:
Command | Name | Parameters | Description |
---|---|---|---|
L (absolute) l (relative) |
lineto | (x y)+ | Draw a line from the current point to the given (x,y) coordinate which becomes the new current point. L (uppercase) indicates that absolute coordinates will follow; l (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. |
H (absolute) h (relative) |
horizontal lineto | x+ | Draws a horizontal line from the current point. H (uppercase) indicates that absolute coordinates will follow; h (lowercase) indicates that relative coordinates will follow. Multiple x values can be provided (although usually this doesn't make sense). An H or h command is equivalent to an L or l 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. |
V (absolute) v (relative) |
vertical lineto | y+ | Draws a vertical line from the current point. V (uppercase) indicates that absolute coordinates will follow; v (lowercase) indicates that relative coordinates will follow. Multiple y values can be provided (although usually this doesn't make sense). A V or v command is equivalent to an L or l 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 l command is used, the end point of the line is (cpx + x, cpy + y).
When a relative h command is used, the end point of the line is (cpx + x, cpy). This means that an h command with a positive x value draws a horizontal line in the direction of the positive x-axis.
When a relative v command is used, the end point of the line is (cpx, cpy + y).
The cubic Bézier commands are as follows:
Command | Name | Parameters | Description |
---|---|---|---|
C (absolute) c (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. C (uppercase) indicates that absolute coordinates will follow; c (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. |
S (absolute) s (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). S (uppercase) indicates that absolute coordinates will follow; s (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 c or s command is used, each of the relative coordinate pairs is computed as for those in an m command. For example, the final control point of the curve of both commands is (cpx + x, cpy + y).
Example cubic01 shows some simple uses of cubic Bézier commands within